RetailCRM API v5: Забирать изменения заказов без полной перевыгрузки

Сценарий из mcp-everything. Актуально на 2026-10-24.

Синхронизация статусов и состава заказов из RetailCRM в свою систему.

Запроси историю: GET /api/v5/orders/history с filter[sinceId] — id последнего обработанного изменения (в первый раз можно начать с filter[startDate]).
Каждая запись истории — одно изменённое поле: field, oldValue, newValue и order, к которому оно относится. Применяй изменения по порядку.
Сохрани id последней записи и в следующий раз передай его в filter[sinceId]. Листай страницы, пока currentPage меньше totalPageCount.
Если нужен заказ целиком, получи его: GET /api/v5/orders/{externalId} с by = externalId (или by = id для внутреннего номера).
Не перевыгружай весь список GET /api/v5/orders по расписанию — история быстрее и не упирается в лимит запросов.

curl -G "https://<поддомен>.retailcrm.ru/api/v5/orders/history" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  -d 'filter[sinceId]=15230' \
  -d limit=100

Базовые URL

Боевой: https://{your-subdomain}.retailcrm.ru/api/v5/

Авторизация

Тип: API-ключ

API-ключ создаётся в аккаунте RetailCRM и передаётся в параметре apiKey (GET или POST). Если ключ даёт доступ к нескольким магазинам, части методов нужен параметр site — символьный код магазина. Запросы — только по HTTPS, кодировка UTF-8.

Методы сценария

GET /api/v5/orders — Список заказов

Параметр	Где	Тип	Обяз.	Описание
`apiKey`	query	string	да	API-ключ
`filter`	query	object	нет	Фильтр: filter[numbers][], filter[externalIds][], filter[customerId], filter[email], filter[minPrice], filter[maxPrice], filter[trackNumber] и др.
`limit`	query	integer	нет	Количество записей на странице
`page`	query	integer	нет	Номер страницы, по умолчанию 1

GET /api/v5/orders/{externalId} — Получить заказ

Параметр	Где	Тип	Обяз.	Описание
`externalId`	path	string	да	Внешний или внутренний ID заказа
`by`	query	string	нет	externalId или id
`site`	query	string	нет	Код магазина

GET /api/v5/orders/history — История изменений заказов

Параметр	Где	Тип	Обяз.	Описание
`filter`	query	object	нет	Фильтр истории
`limit`	query	integer	нет	Количество записей
`page`	query	integer	нет	Страница

Нюансы

POST-запросы отправляются как application/x-www-form-urlencoded, а вложенные структуры (order, customer, offers) — JSON-строкой внутри поля формы.
Для ключа с доступом к нескольким магазинам часть методов требует site.
Ответы списков содержат метаданные пагинации: limit, totalCount, currentPage, totalPageCount.
Для синхронизации изменений используйте /orders/history и /customers/history, а не полную перевыгрузку списков.
Код 460 при пакетной загрузке означает, что часть заказов загружена с ошибками; загруженные перечислены в uploadedOrders.

Другие сценарии

Если этого недостаточно — официальная документация: https://rest-api-docs.retailcrm.ru/v5/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/retailcrm.md