Правила работы с API

  1. Схема
  2. Авторизация
  3. GET-запросы
  4. POST-запросы
  5. Частота обращения к API
  6. Постраничная разбивка ответа / Pagination
  7. Сообщения об ошибках

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

Схема

При работе с API необходимо использовать версию v5. Предыдущие версии API сохранены для совместимости и не рекомендуются к использованию. Вы можете ознакомиться подробнее о версиях и их отличиях в отдельной статье. Запросы необходимо отправлять по адресу:

https://{your-subdomain}.retailcrm.ru/api/{version}/

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

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

Авторизация

Авторизация производится с помощью API-ключа, который передается в GET|POST-параметре apiKey:

https://demo.retailcrm.ru/api/v5/orders?apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh

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

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

GET-запросы

При обращении к API-методам типа GET параметры необходимо отправлять в виде GET-параметров.

Пример передаваемых данных:

https://demo.retailcrm.ru/api/v5/orders?filter[numbers][]=1235C&filter[customFields][nps][min]=5&apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh

POST-запросы

При обращении к API-методам типа POST параметры необходимо отправлять в формате application/x-www-form-urlencoded. При этом если в каком-либо из параметров передается вложенная структура (например, в методе /api/v*/orders/create данные по заказу в параметре order), то значения таких параметров необходимо передавать в виде JSON-строки.

Пример передаваемых данных:

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

Частота обращения к API

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

HTTP/1.1 503 Service Temporarily Unavailable

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

Постраничная разбивка доступна в запросах с потенциально большим ответом, который разбивается на порции.

В данных запросах помимо самого ответа присутствует мета-информация о постраничной разбивке:

HTTP/1.1 200 OK
{ 
    "success": true, 
    "pagination": {
        "limit" => 20,
        "totalCount" => 1583,
        "currentPage" => 1,
        "totalPageCount" => 80
    },
    // data
}

Мета-информация о постраничной разбивке включает:

Если ответ состоит более чем из одной страницы, в запросе доступен GET-параметр page (по-умолчанию равен 1).

Сообщения об ошибках

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

1) Не указан apiKey:

HTTP/1.1 403 Forbidden
{ 
    "errorMsg": "\u0022apiKey\u0022 is missing.", 
    "success": false 
}

2) Неверный apiKey:

HTTP/1.1 403 Forbidden
{ 
    "errorMsg": "Wrong \u0022apiKey\u0022 value.", 
    "success": false 
}

3) Доступ к API ограничен по IP.

HTTP/1.1 403 Forbidden
{
    "success": false,
    "errorMsg": "Forbidden"
}

4) Аккаунт системы не найден

HTTP/1.1 404 Not found
{
    "success": false,
    "errorMsg": "Account does not exist."
}

5) Ошибка на сервере

HTTP/1.1 503 Service Unavailable
{
    "success": false,
    "errorMsg": "Service overloaded."
}

или

HTTP/1.1 500  Internal Server Error
{
    "success": false,
    "errorMsg": "Application error"
}

6) Некорректные данные в параметрах запроса

HTTP/1.1 400 Bad request
{
    "success": false,
    "errorMsg": "Invalid request: Errors in the input parameters",
    "errors": {
        "children[deliveryType]": "This value is not valid."
    }
}

7) Некорректные данные в некоторых элементах входящего массива данных (например, массива заказов)

HTTP/1.1 460 Bad request
{
    "success": false,
    "uploadedOrders": [],
    "errorMsg": "Orders are loaded with errors",
    "errors": [
        "Order with externalId=4414145 already exists.",
        "OrderType with code 'some-code' not found. Order externalId=44141452"
    ]
}

Редакция от 07.05.2020 11:14