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

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

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

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

```bash
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`.

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

- [Передать заказ с сайта в RetailCRM](https://mcp-everything.ru/integrations/retailcrm/scenarios/peredat-zakaz-s-sayta-v-retailcrm.md)
- [Сменить статус заказа и отметить оплату](https://mcp-everything.ru/integrations/retailcrm/scenarios/smenit-status-zakaza-i-otmetit-oplatu.md)
- [Загрузить остатки товаров](https://mcp-everything.ru/integrations/retailcrm/scenarios/zagruzit-ostatki-tovarov.md)

---

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