Интеграция возвратов с 1С 1С-Битрикс

Интеграция возвратов с 1С 1С-Битрикс

Когда покупатель оформляет возврат на сайте, в бэк-офисе нужно создать несколько связанных документов: сторнирование реализации, акт о расхождении, корректировочный счёт-фактура. Если Битрикс и 1С работают независимо — всё это делается вручную, а вероятность расхождений остатков и взаиморасчётов растёт с каждой неделей.

Интеграция возвратов — это отдельный контур внутри обмена 1С–Битрикс, потому что стандартный модуль sale обменивается заказами, а не корректировочными документами. Их нужно описывать отдельно и явно.

Как устроен возврат в Битрикс

Возврат в Битрикс — объект класса \Bitrix\Sale\Payment\PaymentReturn в контексте платежа или \Bitrix\Sale\Shipment\ShipmentReturn в контексте отгрузки. С точки зрения БД это записи в таблицах:

• b_sale_order_return — заявка на возврат
• b_sale_order_return_item — позиции возврата
• b_sale_order_return_shipment — связь с отгрузкой

Статусы возврата (RETURN_STATUS): NEW, PROCESSED, COMPLETED, REJECTED. Триггером для передачи в 1С должен служить переход в COMPLETED — до этого момента данные могут меняться.

Схема обмена

Стандартный модуль bitrix.1c передаёт заказы через sale.order в CommerceML 2. Возвраты в CommerceML не описаны — это кастомный узел, который нужно добавить в схему самостоятельно.

Битрикс: возврат переходит в COMPLETED
  → Обработчик события OnSaleReturnComplete
    → Формирование XML-узла <Возврат>
      → Запись в очередь обмена (b_agent / кастомная таблица)
        → Следующий сеанс обмена с 1С
          → 1С создаёт документ "Возврат товаров от покупателя"
            → Подтверждение из 1С → статус возврата обновляется

Используйте событие OnSaleReturnComplete из модуля sale:

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleReturnComplete',
    function (\Bitrix\Main\Event $event) {
        $return = $event->getParameter('ENTITY');
        ReturnExchangeQueue::push($return->getId());
    }
);

XML-структура для передачи в 1С

1С работает с CommerceML, но возвраты удобнее передавать отдельным узлом внутри <КоммерческаяИнформация>:

<Возврат>
  <Ид>RETURN-{return_id}</Ид>
  <НомерДокумента>R-{return_id}</НомерДокумента>
  <Дата>{date}</Дата>
  <ЗаказИд>{order_id}</ЗаказИд>
  <Контрагент>
    <Ид>{user_id}</Ид>
    <Наименование>{user_name}</Наименование>
  </Контрагент>
  <Товары>
    <Товар>
      <Ид>{product_id}</Ид>
      <Наименование>{product_name}</Наименование>
      <Количество>{qty}</Количество>
      <ЦенаЗаЕдиницу>{price}</ЦенаЗаЕдиницу>
      <Сумма>{sum}</Сумма>
    </Товар>
  </Товары>
  <СуммаВозврата>{total}</СуммаВозврата>
  <Причина>{reason}</Причина>
</Возврат>

На стороне 1С в конфигурации описывается обработчик, который читает этот узел и создаёт документ «Возврат товаров от покупателя» с правильной привязкой к исходной реализации по ЗаказИд.

Синхронизация остатков после возврата

После успешного проведения возврата в 1С остатки обновляются. Важно, чтобы Битрикс получил этот сигнал и обновил b_catalog_store_product. Стандартный обмен остатками (offers.xml) это сделает при следующем сеансе, но если сеансы редкие — нужен отдельный запрос:

// 1С вызывает URL после проведения возврата
// /bitrix/admin/1c_exchange.php?type=catalog&mode=checkauth&return_confirm=Y&return_id=123

$returnId = (int)$_GET['return_id'];
ReturnSyncService::updateStocksFromReturn($returnId);

В updateStocksFromReturn — прямое обновление b_catalog_store_product через \Bitrix\Catalog\StoreProductTable с вызовом \Bitrix\Catalog\StoreBatchService при необходимости пересчёта партий.

Обратная передача статуса

После создания документа в 1С необходимо вернуть в Битрикс подтверждение:

Обновление статуса на стороне Битрикс:

$return = \Bitrix\Sale\OrderReturn::load($returnId);
$return->setField('STATUS', 'COMPLETED');
$return->setField('COMMENTS', '1С: документ #' . $doc1cId);
$return->save();

Кейс: оптовый поставщик, 150+ возвратов в месяц

Клиент — дистрибьютор строительной химии. Возвраты приходили двумя путями: через ЛК дилера на сайте и напрямую от логистики. Проблема: бухгалтерия 1С не видела возвраты из сайта, проводила документы вручную с опозданием 3–5 дней. Это вело к неверным остаткам на складах Битрикс и конфликтам при последующих заказах.

Что сделали:

1. Событие OnSaleReturnComplete пишет возврат в очередь local_1c_return_queue.
2. Агент (каждые 10 минут) формирует XML и передаёт в конечную точку 1С через HTTP-запрос к стандартному обработчику обмена.
3. 1С проводит документ, обновляет остатки, шлёт подтверждение на /api/1c/return-confirm/{returnId}.
4. Вебхук в Битрикс обновляет статус возврата и переоценивает b_catalog_store_product для затронутых SKU.

Состав работ

• Анализ конфигурации 1С: тип документа «Возврат товаров от покупателя», поля привязки к заказу
• Разработка XML-схемы и PHP-генератора для Битрикс
• Обработчик события OnSaleReturnComplete, очередь обмена
• Вебхук-эндпоинт для подтверждения из 1С
• Обновление остатков в Битрикс после подтверждения
• Тестирование на нескольких сценариях: частичный возврат, возврат без отгрузки, возврат с несколькими складами

Сроки: базовая интеграция (передача возвратов, подтверждение) — 3–4 недели. С синхронизацией остатков в реальном времени и обработкой нештатных сценариев — 6–8 недель.