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

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

Каждый заказ интернет-магазина сразу попадает в 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.

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": "Позвонить за час"
  }'

Базовые URL

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

Авторизация

Тип: API-ключ

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

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

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/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-запросы отправляются как 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