Работа с заказами через API

Заказ — центральная сущность RetailCRM, и большая часть интеграций сводится к его созданию, обновлению и синхронизации статусов. Объект order сложносоставной: позиции, оплаты, доставка и клиент связаны в одном теле запроса, поэтому важно понимать его структуру и правила идемпотентности.

Создание заказа

Заказ создаётся методом POST /api/v5/orders/create. Минимально достаточно контактных данных, но на практике передают клиента, позиции, доставку и способ оплаты. Тело — параметр order с JSON и обязательный site:

order={"externalId":"1001","firstName":"Иван","phone":"+79001112233","email":"ivan@example.com","items":[{"offer":{"externalId":"SKU-42"},"quantity":2,"initialPrice":1990}]}

В ответе приходит внутренний id заказа и полный объект. Обязательно сохраняйте связку externalId ↔ id у себя: она нужна для последующих правок и защищает от дублей.

Товарные позиции

Позиции лежат в массиве items. Каждая привязывается к торговому предложению через offer — по id, externalId или xmlId из каталога. Ключевые поля позиции:

Если товара нет в каталоге, можно передать позицию без привязки к offer, указав название в productName. Но для корректной аналитики и списания остатков лучше опираться на каталог.

Редактирование заказа

Изменение выполняется методом POST /api/v5/orders/{identifier}/edit. Идентификатором может быть externalId (по умолчанию) или внутренний id при by=id:

POST /api/v5/orders/1001/edit → order={"status":"assembling"}&by=externalId&site=main

Важные нюансы редактирования позиций:

• массив items при передаче полностью заменяет текущий набор — чтобы удалить позицию, её просто не включают;
• чтобы изменить конкретную позицию, а не пересобирать список, передают её вместе с внутренним id позиции;
• если externalId ещё не привязан, заказ можно найти по id и дописать externalId тем же запросом.

Статусы, оплаты и доставка

Статус заказа задаётся полем status по символьному коду из справочника /reference/statuses. Статусы сгруппированы (новый, комплектация, доставка, выполнен, отменён), и переход между ними может быть ограничен настройками системы.

Оплаты хранятся в массиве payments: тип из /reference/payment-types, статус, сумма. Доставка описывается объектом delivery — код службы, стоимость, адрес и date. Пример смены статуса и фиксации оплаты:

order={"status":"complete","payments":[{"type":"bank-card","status":"paid","amount":3980}]}

Чтение и выборка заказов

Получить один заказ — GET /api/v5/orders/{id}, список с фильтрами — GET /api/v5/orders. Полезные фильтры:

• filter[extendedStatus][] — по статусам;
• filter[createdAtFrom] / filter[createdAtTo] — по дате создания;
• filter[customerId] — заказы клиента;
• filter[sinceId] — для инкрементальной выгрузки.

Для синхронизации изменений с момента последней сессии удобнее не листать всё, а фильтровать по дате обновления и обходить страницы через sinceId. Так вы получаете только новое и не упираетесь в лимиты частоты.

Идемпотентность и защита от дублей

API не хранит ключей идемпотентности, поэтому её обеспечивает разработчик. Базовая стратегия: externalId как естественный ключ заказа.

1. Перед созданием проверьте, нет ли заказа с вашим externalId (чтение по by=externalId).
2. Если есть — вызывайте /edit, если нет — /create.
3. При таймауте ответа не создавайте заказ заново вслепую: сначала перечитайте по externalId.

Итог

Работа с заказами через API строится вокруг объекта order: создание через /create, правки через /edit с полной заменой массива items, статусы и оплаты по справочным кодам. Надёжность интеграции определяется дисциплиной с externalId и защитой от дублей при повторах.

Мы строим двусторонний обмен заказами между сайтом на 1С-Битрикс и RetailCRM: с корректной идемпотентностью, синхронизацией статусов и оплат, обработкой ошибок и логированием. Если заказы должны без потерь ходить между витриной, CRM и учётной системой, поможем реализовать такой обмен.