Інтеграція повернень з 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, черга обміну
• Webhook-ендпоінт для підтвердження з 1С
• Оновлення залишків у Бітрікс після підтвердження
• Тестування на кількох сценаріях: часткове повернення, повернення без відвантаження, повернення з кількох складів

Терміни: базова інтеграція (передача повернень, підтвердження) — 3–4 тижні. З синхронізацією залишків у реальному часі та обробкою нештатних сценаріїв — 6–8 тижнів.