RetailCRM API v5 API

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

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

Сценарии

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

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

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

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 в свою систему.

Запроси историю: 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

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

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

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

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"}'

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

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

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

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.

Источники

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