Link Поиск Меню Развернуть Документ

Подключение к API

«Тройка Бизнес» API v3 представляет собой набор HTTP ресурсов, к которым можно обращаться следующими HTTP методами: GET, POST, PUT, DELETE.

Клиент и сервер производят обмен сообщениями по протоколу HTTPS, который в данном случае играет роль транспортного уровня.

HTTP-заголовки

В запросах необходимо передавать HTTP-заголовки:

Наименование Значение Комментарий
Content-Type application/json Обязательно
Accept application/json Обязательно
User-Agent идентификатор приложения Обязательно. Идентификатор приложения формируется в следующем формате: наименование приложения/версия (версия модуля, если применимо) {иные идентификаторы}.
X-Signature подпись запроса Обязательно

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

Для всех запросов к API обязательно должен присутствовать заголовок Authorization, а также каждый запрос должен иметь подпись, которая передаётся в заголовке X-Signature.

Пример заголовка авторизации: Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

:warning: Идентификатор пользователя API, алгоритм и формат используемой подписи запроса согласовываются на стадии подключения Агента к системе.

Структура и формат запроса

Тело запроса, если оно требуется, должно быть передано в формате json, кодировка UTF-8.

:warning: Наименования параметров, заголовков и свойств объектов во всех запросах чувствительны к регистру.

Тело запроса состоит из корневого объекта message и двух основных дочерних объектов head и body.

В объекте head передаётся информация о вызываемом методе и свойствах клиента. Свойства клиента передаются в параметрах languageId (язык клиента), phone (имя пользователя API), terminalId (идентификатор сервиса Агента), time (дата и время в формате ATOM на стороне клиента). В параметре type передаётся наименование вызываемого метода.

В объекте body передаются параметры вызываемого метода.

Пример запроса на оформление заказа:

{
    "message": {
        "head": {
            "type": "app_create_order",
            "terminalId": "bus_f78a8a6aa7fb3d5",
            "languageId": "ru",
            "phone": "+73946027654",
            "time": "2022-04-22 00:21:02 +03:00"
        },
        "body": {
            "orderData": [
                {
                    "cardNumber": "1234567890",
                    "currencyId": "RUB",
                    "quantity": 1,
                    "tariffId": 2671,
                    "type": "owncard"
                }
            ],
            "phone": "+71044826548"
        }
    }
}

Структура и формат ответа

Все ответы возвращаются в формате json, кодировка UTF-8.

Тело ответа состоит из корневого объекта message и двух основных дочерних объектов head и body. В объекте head передаётся информация об исполненном методе и результате исполнения в параметрах resultCode (код ответа) и resultMessage (описание кода ответа). В случае, если код ответа не равен 0, результат выполнения запроса считается неуспешным. В объекте bodyпередаются дополнительные параметры результата вызванного метода.

Пример ответа на запрос оформления заказа:

{
    "message": {
        "head": {
            "resultCode": 0,
            "resultMessage": "OK"
        },
        "body": {
            "id": 228422,
            "totalAmount": 2800
        }
    }
}

Читать далее »