---
slug: "retailcrm"
name: "RetailCRM API v5"
vendor: "RetailCRM"
industry: "crm"
docsUrl: "https://rest-api-docs.retailcrm.ru/v5/"
version: 2
updatedAt: "2026-10-24"
---

# RetailCRM API v5

Отрасль: CRM и продажи. Актуально на 2026-10-24.

REST API CRM для интернет-магазинов и ритейла RetailCRM: заказы и их история, клиенты, товары и остатки, оплаты, справочники, доставка, телефония, задачи. Запросы выполняются к поддомену аккаунта, ключ передаётся параметром `apiKey`. Актуальная версия — v5, предыдущие сохранены для совместимости и не рекомендуются.

## Сценарии

### Передать заказ с сайта в RetailCRM

Каждый заказ интернет-магазина сразу попадает в CRM с клиентом, товарами, доставкой и оплатой.

1. Создай API-ключ в RetailCRM (Настройки → Интеграция → Ключи доступа к API). Запросы идут на https://<поддомен>.retailcrm.ru/api/v5/, ключ — в параметре apiKey. Если ключ видит несколько магазинов, передавай site — символьный код магазина.
2. Отправь заказ: POST /api/v5/orders/create. Тело — application/x-www-form-urlencoded, а сам order — JSON-строкой в поле формы. Внутри: externalId (номер у тебя), firstName, lastName, phone, email, items (offer с externalId товара и quantity), delivery и customerComment.
3. Клиента RetailCRM создаст по данным заказа. Если клиент у тебя уже есть, создай его заранее через POST /api/v5/customers/create с customer.externalId и привяжи к заказу через order.customer.
4. В ответе — id заказа в RetailCRM. Сохрани его рядом с externalId.
5. Лимит — 10 запросов в секунду с одного IP; при превышении придёт 503.

```bash
curl -X POST "https://<поддомен>.retailcrm.ru/api/v5/orders/create" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  --data-urlencode 'site=my-shop' \
  --data-urlencode 'order={
    "externalId": "1042",
    "orderMethod": "shopping-cart",
    "firstName": "Иван",
    "lastName": "Петров",
    "phone": "+79990001122",
    "email": "ivan@example.ru",
    "items": [{"offer": {"externalId": "SKU-17"}, "quantity": 2, "initialPrice": 990}],
    "delivery": {"address": {"text": "Москва, ул. Тверская, 1, кв. 5"}, "cost": 300},
    "customerComment": "Позвонить за час"
  }'
```

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

Синхронизация статусов и состава заказов из 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
```

### Сменить статус заказа и отметить оплату

Оплата пришла в платёжной системе — заказ в CRM переходит в нужный статус, оплата отмечается.

1. Измени заказ: POST /api/v5/orders/{externalId}/edit с by = externalId и order — JSON-строкой только с изменяемыми полями, например status. Коды статусов видны в настройках RetailCRM.
2. Добавь оплату: POST /api/v5/orders/payments/create с payment — JSON-строкой: order (externalId или id заказа), type (код типа оплаты из справочника), amount, status и paidAt.
3. Если оплата уже создана и нужно поменять её статус, используй /api/v5/orders/payments/{id}/edit.
4. Ошибки валидации приходят с кодом 400 и списком errors — по нему видно, какое поле не прошло.

```bash
curl -X POST "https://<поддомен>.retailcrm.ru/api/v5/orders/1042/edit" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  --data-urlencode 'by=externalId' \
  --data-urlencode 'site=my-shop' \
  --data-urlencode 'order={"status": "assembling"}'

curl -X POST "https://<поддомен>.retailcrm.ru/api/v5/orders/payments/create" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  --data-urlencode 'site=my-shop' \
  --data-urlencode 'payment={"order": {"externalId": "1042"}, "type": "bank-card", "amount": 2280, "status": "paid", "paidAt": "2026-10-24 18:30:00"}'
```

### Загрузить остатки товаров

Синхронизировать остатки со склада, чтобы операторы видели, что есть в наличии.

1. Отправь остатки: POST /api/v5/store/inventories/upload с offers — JSON-строкой: для каждого торгового предложения его externalId (или id) и stores — склады с code и available.
2. За один запрос можно передать много предложений — отправляй изменения пачками, а не по одному товару.
3. Проверь результат: GET /api/v5/store/products с фильтром по товару покажет актуальные остатки.

```bash
curl -X POST "https://<поддомен>.retailcrm.ru/api/v5/store/inventories/upload" \
  --data-urlencode "apiKey=$RCRM_KEY" \
  --data-urlencode 'site=my-shop' \
  --data-urlencode 'offers=[
    {"externalId": "SKU-17", "stores": [{"code": "main", "available": 25}]},
    {"externalId": "SKU-18", "stores": [{"code": "main", "available": 0}]}
  ]'
```

## Базовые 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 | нет | Код магазина |

### POST /api/v5/orders/create — Создать заказ

Тело — `application/x-www-form-urlencoded`; объект `order` передаётся JSON-строкой.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `apiKey` | body | string | да | API-ключ |
| `site` | body | string | нет | Код магазина |
| `order` | body | string (JSON) | да | Заказ |
| `order.externalId` | body | string | нет | Внешний ID |
| `order.number` | body | string | нет | Номер заказа |
| `order.orderType` | body | string | нет | Тип заказа |
| `order.orderMethod` | body | string | нет | Способ оформления, например phone |
| `order.status` | body | string | нет | Статус, например assembling |
| `order.firstName` | body | string | нет | Имя |
| `order.lastName` | body | string | нет | Фамилия |
| `order.patronymic` | body | string | нет | Отчество |
| `order.phone` | body | string | нет | Телефон |
| `order.email` | body | string | нет | Email |
| `order.customer` | body | object | нет | Привязка к клиенту (id и тип) |
| `order.managerId` | body | integer | нет | Менеджер |
| `order.items` | body | array | нет | Позиции: offer, quantity, priceType, purchasePrice и др. |
| `order.delivery` | body | object | нет | Доставка: address, cost, netCost и др. |
| `order.payments` | body | array | нет | Оплаты: type, status, amount, paidAt |
| `order.customFields` | body | object | нет | Пользовательские поля |
| `order.shipmentStore` | body | string | нет | Склад отгрузки |
| `order.shipmentDate` | body | string | нет | Дата отгрузки |
| `order.customerComment` | body | string | нет | Комментарий клиента |
| `order.managerComment` | body | string | нет | Комментарий оператора |

### POST /api/v5/orders/{externalId}/edit — Изменить заказ

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `externalId` | path | string | да | Внешний или внутренний ID заказа |
| `by` | body | string | нет | externalId или id |
| `site` | body | string | нет | Код магазина |
| `order` | body | string (JSON) | да | Изменяемые поля заказа |

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

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

### GET /api/v5/orders/statuses — Статусы заказов

Статусы заказов по списку ID или внешних ID.

### POST /api/v5/orders/payments/create — Создать оплату заказа

Добавляет оплату к заказу. Изменение — `POST /api/v5/orders/payments/{id}/edit`, удаление — `POST /api/v5/orders/payments/{id}/delete`.

### POST /api/v5/orders/upload — Пакетная загрузка заказов

Загружает несколько заказов за раз. При частичных ошибках возвращает нестандартный код `460` с `uploadedOrders` и `errors`.

### GET /api/v5/customers — Список клиентов

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

### POST /api/v5/customers/create — Создать клиента

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `site` | body | string | нет | Код магазина |
| `customer` | body | string (JSON) | да | Клиент |
| `customer.externalId` | body | string | нет | Внешний ID |
| `customer.firstName` | body | string | нет | Имя |
| `customer.lastName` | body | string | нет | Фамилия |
| `customer.email` | body | string | нет | Email |
| `customer.phones` | body | array | нет | Телефоны |
| `customer.address` | body | object | нет | Адрес |
| `customer.managerId` | body | integer | нет | Менеджер |
| `customer.customFields` | body | object | нет | Пользовательские поля |

### POST /api/v5/customers/{externalId}/edit — Изменить клиента

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `externalId` | path | string | да | Внешний или внутренний ID клиента |
| `by` | body | string | нет | externalId или id |
| `site` | body | string | нет | Код магазина |
| `customer` | body | string (JSON) | да | Изменяемые поля |

### GET /api/v5/store/products — Список товаров

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

### POST /api/v5/store/inventories/upload — Загрузка остатков

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `offers` | body | string (JSON) | да | Торговые предложения с остатками |
| `site` | body | string | нет | Код магазина |

## Нюансы

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

## Ошибки

| Код | Описание |
|---|---|
| `400` | Неверные параметры запроса; детали в errors |
| `403` | Не передан или неверен apiKey, либо ограничение по IP |
| `404` | Аккаунт не найден |
| `460` | Заказы загружены с ошибками (uploadedOrders, errors) |
| `500` | Ошибка приложения |
| `503` | Превышен лимит запросов или сервис перегружен |

## Ограничения

- 10 запросов в секунду с одного IP для общих методов.
- 40 запросов в секунду с одного IP для методов телефонии `/api/telephony/*`.
- При превышении — `HTTP/1.1 503 Service Temporarily Unavailable`.

## Источники

- [Документация REST API v5](https://rest-api-docs.retailcrm.ru/v5/)
- [Правила работы с API](https://help.retailcrm.ru/Developers/ApiRules)
- [Официальный PHP-клиент (маршруты и модели запросов)](https://github.com/retailcrm/api-client-php)

---

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