Скопировать ссылку на статью Скопировано Правила работы с API Скопировать ссылку на статью Скопировано

Данное API предназначено для взаимодействия с системой со стороны интеграционных модулей, серверной части сайта, интернет-магазина либо из мобильного приложения. Для взаимодействия с системой из Javascript используйте Daemon Collector.

Содержание

1. Версия, адрес и формат обмена
2. Авторизация
3. Права API-ключа и доступ к магазинам
4. GET-запросы
5. POST-запросы
6. Ограничение частоты запросов
7. Постраничная разбивка ответа

Версия, адрес и формат обмена

Для новых интеграций используйте API v5. Версии v3 и v4 устарели, но их методы продолжают работать для обратной совместимости с существующими интеграциями.

API-ключ не привязан к версии: при создании ключа версию не выбирают, она указывается в адресе метода. Поэтому доступные методы v3 и v4 можно вызвать и с новым ключом, если у него есть необходимые права. Несмотря на это, не создавайте новые интеграции на v3 или v4. Список доступных в аккаунте версий можно получить с помощью авторизованного запроса GET /api/api-versions.

Запросы рекомендуется отправлять на технический домен аккаунта:

{technicalUrl}/api/{version}/

Адрес технического домена можно получить без авторизации с помощью запроса GET https://{your-subdomain}.retailcrm.ru/api/system-info. Он возвращается в поле technicalUrl.

Все запросы принимаются только по https в кодировке UTF-8. Ответ формируется в JSON-формате.

Данные типа «Дата» указываются в формате Y-m-d (например 2014-03-21), данные типа «Дата/время» — в формате Y-m-d H:i:s (например 2014-03-21 05:14:07).

Авторизация

Авторизация производится с помощью API-ключа. Рекомендуемый способ — передавать полное значение ключа в HTTP-заголовке X-API-KEY, без дополнительных префиксов:

X-API-KEY: X2EDxEta9U3lcsSV0dwdF38Uxxxxxxxxx

В GET-запросе API-ключ также можно передать в строке запроса в параметре apiKey:

{technicalUrl}/api/v5/orders?apiKey=X2EDxEta9U3lcsSV0dwdF38Uxxxxxxxxx

В POST-запросе API-ключ также можно передать в теле запроса в параметре apiKey в формате application/x-www-form-urlencoded:

apiKey=X2EDxEta9U3lcsSV0dwdF38Uxxxxxxxxx

Передача API-ключа в параметре apiKey поддерживается, но не рекомендуется: ключ может попасть в журналы запросов и другие служебные данные.

В настройках системы вы найдете раздел по управлению ключами API. В случае отсутствия API-ключа либо в случае, если он неверный, API сообщает об ошибке.

Права API-ключа и доступ к магазинам

Доступ API-ключа к API может быть ограничен определенными действиями, которые можно совершать над группами ресурсов (получение или редактирование).

Узнать, какие действия доступны для API-ключа, можно с помощью метода GET /api/credentials. В поле scopes возвращается массив областей действия, доступных переданному ключу.

Необходимая для вызова область действия указана в описании каждого API-метода.

Если API-ключ дает доступ к данным нескольких магазинов, в некоторых методах дополнительно требуется указывать символьный код магазина в параметре site. В GET-запросе передавайте site в строке запроса, а в POST-запросе — в теле запроса. Требование указывать магазин приведено в описании конкретного метода.

GET-запросы

Параметры методов GET передаются в строке запроса. API-ключ рекомендуется передавать отдельно в заголовке X-API-KEY.

Пример адреса запроса:

{technicalUrl}/api/v5/orders?filter[numbers][]=1235C&filter[customFields][nps][min]=5

Заголовок авторизации для этого запроса:

X-API-KEY: X2EDxEta9U3lcsSV0dwdF38Uxxxxxxxxx

POST-запросы

Параметры методов POST передаются в теле запроса в формате application/x-www-form-urlencoded. API-ключ рекомендуется передавать отдельно в заголовке X-API-KEY.

Если параметр содержит вложенную структуру, его значение передается в виде JSON-строки. Например, в методе /api/v5/orders/create данные заказа передаются в параметре order.

Пример заголовков:

X-API-KEY: X2EDxEta9U3lcsSV0dwdF38Uxxxxxxxxx
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Пример тела запроса:

site=simple-site&order=%7B%22externalId%22%3A%22a123%22%2C%22firstName%22%3A%22Tom%22%7D

Ограничение частоты запросов

К API можно обращаться не чаще 10 раз в секунду с одного IP-адреса. Для методов телефонии /api/telephony/* ограничение составляет 40 запросов в секунду с одного IP-адреса. При превышении ограничения API возвращает ответ:

HTTP/1.1 503 Service Temporarily Unavailable

Постраничная разбивка ответа

Для методов, которые могут вернуть большое количество элементов, ответ разбивается на страницы.

В ответе таких методов вместе с данными возвращается объект pagination:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "success": true, 
    "pagination": {
        "limit": 20,
        "totalCount": 1583,
        "currentPage": 1,
        "totalPageCount": 80
    },
    "orders": []
}

Объект pagination содержит:

• limit — количество элементов в текущем ответе;
• totalCount — общее количество элементов;
• currentPage — номер текущей страницы;
• totalPageCount — общее количество страниц.

Для получения нужной страницы передайте её номер в параметре page строки запроса. По умолчанию используется страница 1.