Организация взаимодействия

Общая информация

Для разграничения прав доступа при работе с Data API применяются специализированные токены.

Каждый такой токен формируется через интерфейс Dashboard и ассоциируется с конкретной учётной записью и правами доступа этой записи к проектам мерчанта. Также в связке с токеном формируется секретный ключ, который должен применяться при подписывании запросов с использованием этого токена и проверке ответов, получаемых по таким запросам (подробнее — в разделе Работа с подписью).

Рис.: Сформированные токен и секретный ключ

На стороне платёжной платформы при работе с токенами учётных записей Dashboard обеспечивается соблюдение следующих правил:

• каждый токен представляет собой строку из 30 символов в кодировке UTF-8;
• каждый токен признаётся действительным с момента его формирования и до момента, пока не сформирован новый токен или не выполнена деактивация этого токена, при этом повторно активировать деактивированный токен нельзя;
• для одной учётной записи может быть сформировано произвольное количество токенов, но при этом действительным всегда признаётся только один — сформированный последним;
• любой действительный токен может использоваться произвольное количество раз без ограничений по времени действия;
• в платформе обеспечивается синхронизация информации о правах доступа через учётную запись и ассоциированный с ней токен, благодаря чему при внесении изменений в права учётной записи не требуется формирование нового токена;
• пользователи с правами управления токенами могут формировать и деактивировать токены для своих учётных записей без каких-либо технических ограничений;
• удаление учётной записи пользователя не приводит к автоматической деактивации токена, но все права доступа к данным по этому токену отзываются, поэтому в ответ на запрос с таким токеном от платформы отправляется ответ с отказом в доступе (401 Authorization Required).

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

Предоставление права управления токенами

Как и в случае с другими правами для работы с Dashboard, предоставить и отозвать право управления токенами может только тот пользователь, который обладает учётной записью с ролью Merchant admin.

Предоставить и отозвать право управления токенами может только пользователь с ролью Merchant admin. Чтобы предоставить право управления токенами, со стороны такого пользователя необходимо:

Чтобы предоставить право управления токенами, со стороны такого пользователя необходимо:

1. Перейти в раздел Моя команда.
2. Открыть карточку требуемой учётной записи, щёлкнув кнопку в соответствующей строке реестра.
3. Установить флажок Управление API токенами, щёлкнуть кнопку Сохранить изменения и подтвердить внесение изменений.
   
   
4. Установить флажок Управление API токенами и сохранить изменения.
5. Убедиться, что право предоставлено, проверив, что в карточке учётной записи установлен флажок Управление API токенами.

Чтобы отозвать право управления токенами, необходимо перейти в раздел Моя команда, открыть карточку требуемой учётной записи, снять флажок Управление API токенами, сохранить изменения и убедиться, что они вступили в силу. В этом случае блокируется возможность формировать новый и деактивировать действительный токен для данной учётной записи, но остаётся возможность использовать действительный токен.

Формирование и деактивация токена

Формировать и деактивировать токены можно только для тех учётных записей, которым предоставлено право управления токенами.

Чтобы сформировать и подготовить к работе токен и секретный ключ, пользователю с такой учётной записью необходимо:

1. Перейти в раздел Мой профиль, справа в главном меню интерфейса щёлкнув имя учётной записи и выбрав пункт Мой профиль.
2. Щёлкнуть кнопку Новый токен на панели API-токены.

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

3. Скопировать и сохранить значения токена и секретного ключа, с соблюдением внутренних правил информационной безопасности, действующих на стороне мерчанта.
   Ограничение: Секретный ключ отображается в явном виде только до первого обновления страницы, после чего скрывается и более не является доступным. При необходимости, например если ключ был утерян или скомпрометирован, следует сформировать новую пару токен-ключ.

Чтобы деактивировать токен, в профиле учётной записи на панели API-токены следует щёлкнуть кнопку Удалить. После этого токен становится недействительным и не может применяться для работы с Data API.

Общая информация

В рамках взаимодействия с платёжной платформой через Data API все данные от сервиса мерчанта должны передаваться в запросах — сообщениях HTTP заданной структуры — с использованием метода POST. Описание общей структуры таких запросов представлено далее, а описание структур данных для конкретных запросов — в спецификации интерфейса.

Структура

В каждом запросе к платёжной платформе должны передаваться следующие элементы в указанном порядке:

• стартовая строка с указанием метода передачи запроса (POST) и конечной точки в интерфейсе Data API (например, v1/operations/get), протокола и его версии (HTTP/1.1);
• заголовок с полем Host, содержащим доменное имя для запросов через Data API (data.ecommpay.com/v1);
• пустая строка — разделитель, отделяющая служебную информацию от тела сообщения;
• тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним.

В дополнение к обязательному полю Host в заголовке можно использовать любые другие поля из числа допустимых в HTTP версии 1.1. Далее представлен пример запроса с рекомендуемым набором полей заголовка и обязательными параметрами. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения.

POST v1/balance/get HTTP/1.1
User-Agent: curl/7.29.0
Host: data.ecommpay.com/v1
Accept: */*
Content-Length: 179
Content-Type: application/x-www-form-urlencoded
                    
{
    "token":"ZOyTL5shY8...dQyplRPJYmGV7Kv",
    "signature":"...dQcIbv94Z0nPTYX9s2XqYrY9bzkfcBGQ==..."
}                

Параметры адресации

При формировании запросов необходимо указывать базовый и относительный адреса отправки. В качестве базового адреса для запросов через Data API используется доменное имя data.ecommpay.com/v1, а в качестве относительного — указатель конечной точки в интерфейсе в соответствии со спецификацией.

Тело

В теле сообщения должна содержаться JSON-строка с набором данных в формате "<название параметра>": <значение параметра>. Чтобы предотвратить утечку и подмену данных во время их передачи в платёжную платформу, в составе JSON-строки используются токен и подпись, а на транспортном уровне передачи — протокол TLS 1.2, обеспечивающий шифрование. Подробная информация о формировании токена представлена в пункте Порядок доступа к данным, а о формировании подписи — в разделе Работа с подписью.

В теле сообщения должна содержаться JSON-строка с набором данных в формате "<название параметра>": <значение параметра>, включая токен и подпись. Подробная информация о формировании токена представлена в пункте Порядок доступа к данным, а о формировании подписи — в разделе Работа с подписью.

Общая информация

Со стороны платёжной платформы получение запроса подтверждается отправкой ответа — HTTP-сообщения заданной структуры — в рамках того же сеанса. Передаваемые в ответе данные включают в себя:

• запрошенную информацию, если запрос был выполнен;
• сведения об ошибке, если запрос не может быть выполнен.

Далее представлена информация об общей структуре ответов, а также о кодах, используемых для передачи информации о состоянии запроса. Описание структур данных для ответов на конкретные запросы представлено в спецификации интерфейса.

Структура

В каждом ответе от платформы содержатся следующие элементы в порядке перечисления:

• стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к коду (например, 200 OK);
• поля заголовка;
• пустая строка — разделитель, отделяющая служебную информацию от тела сообщения;
• тело сообщения, содержащее JSON-строку в кодировке UTF-8 в с набором данных.

Коды ответа

HTTP-код ответа используется в стартовой строке каждого ответа для передачи информации о результате выполнения запроса либо о причине обнаруженной ошибки. В работе с Data API применяются следующие коды ответов и пояснительные фразы.

Информация об ошибках

Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки (в примере далее — 401 Authorization Required), а в теле может указываться расширенная информация об этой ошибке:

• поясняющая фраза к коду из заголовка ответа в параметре name (в примере — Authorization Required);
• описание ошибки в параметре message (если ошибка была обработана в платформе; в примере — You have no access to project_id = 22);
• служебный код в параметре code с фиксированным значением 0;
• код из заголовка ответа в параметре status (в примере —400).

POST /v1/balance/get HTTP/1.1         // Запрос от веб-сервиса на получение балансов
                    
HTTP/1.1 400 Bad Request                 // Ответ от платёжной платформы
Server: nginx/1.14.2
Date: Thu, 17 August 2020 10:21:45 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 17 August 2020 10:21:45 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,
User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"name":"Bad Request",
	"message":"You have no access to project_id = 22",
	"code":"0",
	"status":"400"
}