Заказ, оформленный на сайте, должен без ручного ввода превратиться в «Заказ покупателя» в МойСклад, а его статусы отгрузки и оплаты — вернуться на витрину. Правильный обмен заказами избавляет менеджеров от двойного ввода и рассинхрона.
Как устроен поток заказа
Жизненный цикл заказа в связке выглядит так:
- Покупатель оформляет заказ на сайте Битрикс — создаётся запись в
b_sale_order. - Срабатывает событие, обмен формирует документ «Заказ покупателя» в МойСклад через JSON API.
- Менеджер в МойСклад обрабатывает заказ: резерв, отгрузка, оплата.
- Статусы возвращаются на сайт и меняют статус заказа Битрикс.
Ключевое требование ко всему потоку — идемпотентность: повторная отправка того же заказа не должна создавать дубль документа. Второе требование — прослеживаемость: по номеру заказа на сайте всегда должно быть понятно, какой документ ему соответствует в МойСклад, в каком он статусе и когда последний раз синхронизировался. Без этого разбор спорных ситуаций с клиентом превращается в ручной поиск по двум системам.
На каком событии передавать заказ
В Битрикс есть несколько точек, где можно перехватить заказ. Выбор влияет на то, сколько «мусорных» заказов уедет в учёт.
| Событие | Когда срабатывает | Комментарий |
|---|---|---|
OnSaleOrderSaved | При любом сохранении заказа | Универсально, нужна проверка на дубль |
OnSaleStatusOrderChange | При смене статуса | Передавать только после «Принят» |
OnSaleOrderPaid | После оплаты | Для схемы «сначала деньги» |
Сопоставление позиций и контрагентов
Чтобы документ в МойСклад собрался корректно, обмен должен найти соответствие каждой позиции и покупателя.
- Товары сопоставляются по артикулу/коду — тому же ключу, что используется при выгрузке каталога (
XML_ID). - Покупатель ищется среди контрагентов по телефону или email; если не найден — создаётся новый, чтобы не плодить дубли.
- Доставка добавляется отдельной услугой или пишется в поля документа.
- Скидки и промокоды переносятся как цена позиции или отдельная строка скидки.
Идемпотентность и защита от дублей
Событие сохранения может сработать несколько раз, а обмен — уйти в повтор после сбоя сети. Без защиты это порождает дубли документов.
- После создания документа сохраняйте его ID из МойСклад в свойстве заказа Битрикс (например,
MS_DOCUMENT_ID). - Перед отправкой проверяйте это свойство: если ID уже есть — не создаём, а обновляем документ.
- Используйте внешний код
externalCodeв МойСклад, равный номеру заказа Битрикс, — это второй барьер против дублей.
Обратный проброс статусов
Обратный поток так же важен, как прямой: клиент и менеджеры должны видеть на сайте актуальное состояние заказа.
| Событие в МойСклад | Статус на сайте Битрикс |
|---|---|
| Создана отгрузка | Отгружен / Передан в доставку |
| Проведён входящий платёж | Оплачен |
| Заказ отменён | Отменён |
Проброс делается либо периодическим опросом документов МойСклад, либо вебхуками на изменение отгрузок и платежей. Флаг оплаты в Битрикс правильнее ставить через \Bitrix\Sale\Order и setPaid('Y'), чтобы корректно отработала логика скидок и списаний.
Изменения, отмены и возвраты
Заказ живёт не только в момент создания — его правят, отменяют и возвращают. Обмен должен корректно отрабатывать весь цикл, а не только первичную передачу.
- Правка состава. Если менеджер меняет позиции на сайте, обновляйте существующий документ в МойСклад по сохранённому ID, а не создавайте новый.
- Отмена. Отменённый на сайте заказ должен снять резерв в МойСклад и перевести документ в соответствующее состояние.
- Возврат. Оформление возврата в учёте может возвращать товар в доступный остаток и менять статус заказа на сайте.
Обработка ошибок обмена
Сеть, лимиты API и несопоставленные данные будут давать сбои — важно, чтобы заказ не терялся.
- Каждую передачу логируйте с телом запроса и ответом API.
- При ошибке ставьте заказ в очередь на повтор, а не отбрасывайте.
- Разделяйте временные ошибки (сеть, 5xx, лимит) и постоянные (некорректные данные, 400) — первые повторяйте, вторые отправляйте на ручной разбор.
- Настройте алерт, если заказ не ушёл в учёт дольше заданного времени.
Повторы делайте с нарастающей задержкой (экспоненциальный backoff), чтобы не добить внешний API при кратковременном сбое. Очередь с ограниченным числом попыток и «карантином» безнадёжных заказов удобно разбирать вручную, не теряя данные.
Итог
Надёжный обмен заказами держится на трёх принципах: передавать заказ на осмысленном статусе, гарантировать идемпотентность через хранение ID документа, обрабатывать ошибки с очередью повторов. Обратный проброс статусов оплаты и отгрузки замыкает цикл и убирает ручную сверку.
Мы в B2Bsite реализуем двусторонний обмен заказами с защитой от дублей, логами и мониторингом, а при необходимости — со сквозной схемой сайт → CRM → склад. Поможем настроить связку так, чтобы ни один заказ не потерялся между системами.
Частые вопросы
На каком статусе передавать заказ в МойСклад?
Обычно при переходе в статус «Принят» или «Оформлен», а не сразу при создании. Так брошенные и недооформленные корзины не попадают в учётную систему.
Как избежать дублей заказов в МойСклад?
Хранить ID созданного документа в свойстве заказа Битрикс и проверять его перед отправкой, а также использовать externalCode, равный номеру заказа. Это обеспечивает идемпотентность.
Что делать, если товара из заказа нет в МойСклад?
Обработать явно: либо создать позицию по данным заказа, либо пометить заказ для ручной проверки. Нельзя допускать, чтобы обмен молча падал.
Как статусы возвращаются на сайт?
Через периодический опрос документов МойСклад или вебхуки на отгрузки и платежи. Отгрузка меняет статус на «Отгружен», проведённый платёж — на «Оплачен».
Переносятся ли скидки и промокоды?
Да, скидка переносится как изменённая цена позиции или отдельной строкой в документе. Логику маппинга согласуют заранее, чтобы суммы совпадали с сайтом.
Что происходит при сбое сети во время передачи?
Заказ ставится в очередь на повтор, а не теряется. Временные ошибки повторяются автоматически, постоянные — уходят на ручной разбор с логом ответа API.
Можно ли передавать и юрлиц, и физлиц?
Да. Физлицо заводится контрагентом по телефону/email, юрлицо — с реквизитами из свойств заказа. Тип контрагента определяется по данным оформления.
Поможем с настройкой и поддержкой Интеграции и связки систем
Поможем с настройкой, доработкой и поддержкой Интеграции и связки систем.