# 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.

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

## Базовые 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://mcp-everything.ru/integrations/retailcrm/scenarios/zabirat-izmeneniya-zakazov-bez-polnoy.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