Данное API предназначено для взаимодействия с системой со стороны интеграционных модулей, серверной части сайта, интернет-магазина либо из мобильного приложения. Для взаимодействия с системой из Javascript используйте Daemon Collector.
Важно!
При загрузке заказов/клиентов в систему рекомендуем отключать все триггеры, отвечающие за отправку E-mail и SMS сообщений.
Схема
При работе с 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-ключ можно передавать через заголовок X-API-KEY: X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh
В настройках системы вы найдете раздел по управлению ключами API. В случае отсутствия API-ключа либо в случае, если он неверный, API сообщает об ошибке.
Если API-ключ дает доступ к данным нескольких магазинов, то в некоторых API-методах дополнительно требуется указывать символьный код магазина в GET|POST-параметре site. В справочнике вы можете посмотреть, какие методы требуют указания магазина.
Области действия API-ключей
Доступ API-ключа к API может быть ограничен определенными действиями, которые можно совершать над группами ресурсов (получение или редактирование).
Узнать, какие действия доступны для API-ключа, можно с помощью API метода /api/credentials. В поле scopes будет возвращен массив областей действий, доступный переданному ключу.
Найти информацию о том, какая область API необходима для доступа к методу, можно в описании каждого API метода.
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
}Мета-информация о постраничной разбивке включает:
limit — количество элементов в текущем ответе
totalCount — общее количество элементов
currentPage — текущая страница
totalPageCount — общее количество страниц с ответом
Если ответ состоит более чем из одной страницы, в запросе доступен GET-параметр page (по-умолчанию равен 1).