Данное 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
. В справочнике вы можете посмотреть, какие методы требуют указания магазина.
При обращении к API-методам типа GET
параметры необходимо отправлять в виде GET-параметров.
Пример передаваемых данных:
https://demo.retailcrm.ru/api/v5/orders?filter[numbers][]=1235C&filter[customFields][nps][min]=5&apiKey=X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
При обращении к 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 разрешается обращаться не чаще 10 запросов в секунду с одного IP. К методам телефонии /api/telephony/*
разрешается обращаться не чаще 40 запросов в секунду с одного IP. В случае более высокой нагрузки API будет отдавать ответ:
HTTP/1.1 503 Service Temporarily Unavailable
Постраничная разбивка доступна в запросах с потенциально большим ответом, который разбивается на порции.
В данных запросах помимо самого ответа присутствует мета-информация о постраничной разбивке:
HTTP/1.1 200 OK
{
"success": true,
"pagination": {
"limit" => 20,
"totalCount" => 1583,
"currentPage" => 1,
"totalPageCount" => 80
},
// data
}
Мета-информация о постраничной разбивке включает:
limit
— количество элементов в текущем ответе
totalCount
— общее количество элементов
currentPage
— текущая страница
totalPageCount
— общее количество страниц с ответом
Если ответ состоит более чем из одной страницы, в запросе доступен 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"
]
}