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

статья о том, как строится работа с платформой через Data API и как можно организовывать получение необходимых данных

**На уровень выше:**[Использование Data API](ru_dbl_api_protocol.md)

## Схема работы {#ru_dbl_api_info}

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

![](images/universal/dbl/ru_dbl_uml.svg)

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

## Порядок доступа к данным {#ru_dbl_api_token}

### Общая информация {#section_nlt_2nb_tmb .section}

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

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

![](images/ecommpay/dbl/ru_dbl_api_token.svg "Сформированные токен и секретный ключ")

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

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

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

### Предоставление права управления токенами {#section_xp4_y5l_5mb .section}

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

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

1.  Перейти в раздел **Моя команда**.
2.  Открыть карточку требуемой учётной записи, щёлкнув кнопку ![](images/universal/dbl/icon_pencil.svg) в соответствующей строке реестра.
3.  Установить флажок **Управление API токенами**, щёлкнуть кнопку **Сохранить изменения** и подтвердить внесение изменений.

    ![](images/ecommpay/dbl/ru_dbl_user_api.svg)

4.  Убедиться, что право предоставлено, проверив, что в карточке учётной записи установлен флажок **Управление API токенами**.

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

### Формирование и деактивация токена {#section_r3q_gnb_tmb .section}

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

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

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

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

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

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


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

## Формат запросов {#ru_dbl_request_format}

### Общая информация {#section_tw5_bf1_xmb .section}

В рамках взаимодействия с платёжной платформой через Data API все данные от сервиса мерчанта должны передаваться в *запросах* — сообщениях HTTP заданной структуры — с использованием метода POST. Описание общей структуры таких запросов представлено далее, а описание структур данных для конкретных запросов — [в спецификации интерфейса](https://api-data.ecommpay.com/).

### Структура {#section_oyr_nmh_smb .section}

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

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

В дополнение к обязательному полю `Host` в заголовке можно использовать любые другие поля из числа допустимых [в HTTP версии 1.1](https://tools.ietf.org/html/rfc2616#page-31). Далее представлен пример запроса с рекомендуемым набором полей заголовка и обязательными параметрами.Содержимое 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==..."
}                
```

### Параметры адресации {#section_b3q_bsx_thb .section}

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

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

### Тело {#section_kdx_ptx_thb .section}

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

## Формат ответов {#ru_dbl_response_format}

### Общая информация {#section_e4m_cg1_xmb .section}

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

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

Далее представлена информация об общей структуре ответов, а также о кодах, используемых для передачи информации о состоянии запроса. Описание структур данных для ответов на конкретные запросы представлено [в спецификации интерфейса](https://api-data.ecommpay.com/).

### Структура {#section_c2t_tbm_xhb .section}

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

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

### Коды ответа {#section_aj3_knq_13b .section}

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

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

### Информация об ошибках {#section_gxv_5mh_smb .section}

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