Mandarin

# Основные принципы

# Точки входа

Боевое (production) окружение для авторизации: https://accounts.mandarinbank.com/ (opens new window) Боевое (production) окружение для запросов: https://api.psp.io/ (opens new window)

# Аутентификация запросов

Каждый запрос должен быть аутентифицирован с помощью токена (access_token), полученного в соответствии с протоколом OAuth 2.0 для приложений. Токен действует в течение 36 000 секунд (10 часов). Если срок действия истек, токен нужно запросить еще раз.

Запрос на получение токена

Включает в себя обязательные form-data параметры, которые передаются в теле запроса (параметры application.client_id и application.client_secret неизменны для приложения и хранятся на стороне клиента).

Параметр Описание Пример
grant_type Грант авторизации (всегда равен client_credentials). client_credentials
client_id Идентификатор клиента (равен значению application.client_id, предоставленному Mandarin). VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret Секретный ключ-пароль клиента (равен значению application.client_secret, предоставленному Mandarin). uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope Запрашиваемые скоупы (области доступа):
например, transactions.read - "Чтение транзакций".
Разделитель - пробел.
Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.		 transactions.read
curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=transactions.read'

Ответ

Параметр Описание Пример
access_token Токен (ключ доступа). VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in Срок действия токена (в секундах). Всегда равен 36 000 секунд (10 часов). 36000
token_type Тип токена (всегда равен Bearer). Bearer
scope Разрешенные скоупы (области доступа): например, transactions.read - "Чтение транзакций".
Разделитель - пробел.
Запрашивать можно любой список скоупов, при этом в ответе вернется тот список запрошенных скоупов, который может быть предоставлен для данного приложения.		 transactions.read
{
    "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "transactions.read"
}

Использование токена

Указывается в headers каждого запроса, в поле Authorization, после зарезервированного слова Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

# Принципы работы

API реализовано в соответствии с принципами REST API.

API оперирует ресурсами, которые представляют сущности - объекты бизнес-логики (бизнес-модели, доме́нные модели, модели предметной области). Существует два основных типа ресурсов: ресурс коллекции и ресурс сущности.

Ресурсы коллекций названы во множественном числе, например: /transactions.

Ресурс сущности — это ресурс конкретной сущности в какой-то коллекции. Доступ к нему осуществляется всегда через ресурс коллекции и по уникальному номеру, например:

/transactions/{{id}}

API использует JSON как для ответов, так и для запросов (если это применимо). Ответы API стандартизированы.

Ответы ресурсов коллекции всегда содержат поле, названное так же, как и сам ресурс, и содержащее массив бизнес моделей. Если в ответ на запрос данных нет, то массив будет пустой. Например, если это ответ ресурса /transactions, то ответ будет такой:

{  
   "transactions": [  
      { {{transaction_model}} },  
      { ... },  
      { ... }  
   ]  
}

Допустимые параметры запроса:

  • filter_by - выборка по заданным полям и условиям;

  • sort_by - список полей (через запятую) для сортировки в порядке “по убыванию” (добавив минус - перед названием поля, можно переключить порядок сортировки на “по возрастанию”). По умолчанию отсортирован по id;

  • limit_to - ограничить количество сущностей, выдаваемое за один раз; число, по умолчанию 50;

  • cursor - используется для получения следующей/предыдущей части выдачи, имеет приоритет над остальными запросами, то есть, если передаётся cursor, то остальные параметры игнорируются.

Параметр filter_by формируется следующим образом: список полей и значений, по которому нужно отфильтровать сущности, операторы сравнения (=, >, >=, <, <=, возможно использование оператора IN), фильтры объединяются знаком амперсанда: & (который обозначает логический оператор AND).

Формируется следующая строка:

field_name1=value1&field_name2 in value2_1,value2_2&field_name3>=value3_1&field_name3<value3_2

Например, mw_type=transaction&opcode in 1,3&updated>=2019-10-01&updated<2019-10-31.

После чего эта строка URL-энкодится и передаётся как значение параметра filter_by:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31

Параметры верхнего уровня sort_by и limit_to и их значения не URL-энкодятся.

Пример результирующего query-string:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

Ответы ресурсов коллекции всегда содержат вложенный объект пагинации (курсор). Объект курсора всегда содержит поля:

  • count - количество сущностей в текущем ответе.

  • total - общее количество сущностей по данному запросу (с такими фильтрами и т.д.).

  • next - указатель на следующую страницу выдачи (null, если такая страница не существует).

  • prev - указатель на предыдущую страницу выдачи (null, если такая страница не существует).

Пример запроса, который вернет первые 100 сущностей:

GET /transactions?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

{
   "transactions": [ ... ],
   "cursor": {
      "count": 100,
      "next": "aad0f17a6af11672",
      "prev": "f0bb6887c3b2f501",
      "total": 4200
   }
}

Пример запроса для получения последующих 100 сущностей (в параметр cursor подставлено значение из поля ответа next):

GET /transactions?cursor=aad0f17a6af11672

Ответы ресурсов сущностей всегда содержат поле, названное так же, как и сам ресурс, но в единственном числе, например:

GET /transactions/12345

{  
   "transactions": {  
      {{transaction_model}}  
   }  
}

← Для транзакций →