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

Схема работы

При использовании Data API взаимодействие между сервисом мерчанта и платёжной платформой ecommpay строится на обмене сообщениями HTTP по принципу «запрос-ответ» — с запросами от сервиса и ответами от платформы. При этом применяется синхронная схема взаимодействия, в рамках которой в ходе одного сеанса HTTP обрабатывается один запрос и отправляется однократный ответ на него, с запрошенной информацией или с информацией об ошибке.

При использовании Data API применяется синхронная схема взаимодействия, в рамках которой в ходе одного сеанса HTTP обрабатывается один запрос и отправляется однократный ответ на него. Вместе с тем, время выполнения одного запроса на стороне платформы может варьироваться: от десятков миллисекунд до нескольких минут (как правило, не более пяти).

Такая схема работы обусловлена тем, что все запросы, принимаемые через Data API (например, о балансах по проектам мерчанта), подразумевают выполнение на стороне платёжной платформы, без задействования других сервисов и систем. Вместе с тем, с учётом сложности запросов и объёма подготавливаемых данных, время выполнения одного запроса на стороне платформы может существенно варьироваться: от десятков миллисекунд до нескольких минут (как правило, не более пяти).

Порядок доступа к данным

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

Для разграничения прав доступа при работе с 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, а в качестве относительного — указатель конечной точки в интерфейсе в соответствии со спецификацией.

Прим.: Полный адрес в этом случае представляет собой строку вида https://{доменное имя платформы для запросов через Data API}/{указатель конечной точки}. Например, адрес для запроса на получение балансов по проектам мерчанта выглядит как https://data.ecommpay.com/v1/v1/balance/get, но в таком виде при работе с POST-запросами полные адреса не используются.

Тело

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

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

Формат ответов

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

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

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

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

Структура

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

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

Коды ответа

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

Код с пояснением Описание
200 OK Запрос успешно выполнен. В теле ответа передана запрошенная информация
400 Bad Request Запрос не может быть принят из-за синтаксической ошибки, обнаруженной при извлечении данных из JSON-строки, или из-за отсутствия в наборе извлечённых данных обязательных параметров (кроме токена и подписи)
401 Authorization Required Запрос не может быть принят из-за отказа в доступе, например если в запросе некорректно переданы токен или подпись либо указан идентификатор проекта, к которому нет доступа через используемый токен
500 Internal Error Запрос не может быть выполнен из-за сбоя в платёжной платформе

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

Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки (в примере далее — 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"
}