Інтеграція повернень з онлайн-касою 1С-Бітрікс

Інтеграція повернень з онлайн-касою 1С-Бітрікс

За 54-ФЗ при поверненні грошей покупцю каса зобов'язана пробити чек з ознакою розрахунку «Повернення приходу». Якщо сайт працює з онлайн-касою через Бітрікс — повернення має автоматично формувати фіскальний документ через той самий канал. Без цього виникає порушення: гроші повернуто, чек не пробито.

Як Бітрікс взаємодіє з касою

Модуль sale.cashbox (bitrix/modules/sale/cashbox/) відповідає за фіскалізацію. Чеки надсилаються через обробники (handlers), що наслідують від \Bitrix\Sale\Cashbox\CashboxPaymaster або \Bitrix\Sale\Cashbox\CashboxAtol. Стандартні обробники: Атол Онлайн, CloudKassir, OrangeData, ЮKassa та інші.

При оплаті замовлення Бітрікс викликає \Bitrix\Sale\Cashbox\Manager::sendCheck() з типом чека CHECK_TYPE_SELL (прихід). При поверненні — CHECK_TYPE_SELL_RETURN (повернення приходу).

Таблиці: b_sale_cashbox_check — історія чеків, b_sale_cashbox — налаштовані каси.

Як формується чек повернення

Чек повернення Бітрікс створює автоматично при виконанні двох умов:

1. Повернення переходить у статус COMPLETED
2. До вихідного платежу прив'язана каса і вже є підтверджений фіскальний чек приходу

Код, який це запускає — \Bitrix\Sale\Cashbox\Manager::addByReturn():

// Всередині обробника події OnSaleReturnComplete
\Bitrix\Sale\Cashbox\Manager::addByReturn($return);

Якщо у вас нестандартний сценарій (повернення створюється зовнішнім скриптом), потрібно викликати цей метод вручну після збереження повернення.

Що йде в чек повернення

Позиції чека формуються з b_sale_order_return_item. Кожна позиція містить:

• Найменування товару (з b_iblock_element.NAME через JOIN на b_sale_basket.PRODUCT_ID)
• Кількість
• Ціну
• Ставку ПДВ
• Ознаку предмета розрахунку (товар/послуга/робота) — береться з налаштувань позиції замовлення

Якщо у вихідному замовленні ПДВ не вказано або вказано некоректно — у чеку повернення буде помилка. Це часта проблема при міграції з Бітрікс на нову касову схему.

Типові проблеми

Чек повернення не надсилається. Причина: повернення створено не через \Bitrix\Sale\OrderReturn, а напряму в БД або через неофіційний механізм — подія OnSaleReturnComplete не спрацьовує. Рішення: завжди використовуйте ORM-методи.

Помилка «Сума повернення перевищує суму приходу». Касовий оператор відхиляє чек, якщо сума повернення більша, ніж у вихідному чеку приходу. Буває при часткових поверненнях кількох платежів за одне замовлення — кожен чек повернення має бути прив'язаний до конкретного чека приходу через PARENT_CHECK_ID у b_sale_cashbox_check.

Дублювання чека при повторному запиті. При збої мережі Бітрікс може надіслати запит двічі. У Атол Онлайн є параметр external_id — унікальний ідентифікатор чека на вашому боці. Використовуйте його, щоб оператор міг визначити дублікат.

Часткове повернення кількох позицій з одного замовлення. Чек має містити лише позиції, що повертаються, з правильними кількостями. Стандартний Manager::addByReturn() це забезпечує, якщо b_sale_order_return_item заповнено коректно.

Тестування фіскалізації повернень

Всі касові оператори надають тестове середовище. Атол Онлайн — тестовий URL https://testonline.atol.ru/possystem/v5/. OrangeData — тестові ключі та сертифікати.

Перевірочний список перед запуском у прод:

Налаштування сповіщень про помилки фіскалізації

Якщо чек повернення не пройшов — касовий оператор поверне помилку. Бітрікс збереже її в полі ERROR таблиці b_sale_cashbox_check, але за замовчуванням менеджер про це не дізнається. Налаштуйте агент:

// Агент: кожні 30 хвилин перевіряє необроблені помилки
$checks = \Bitrix\Sale\Cashbox\CheckManager::getList([
    'filter' => [
        'STATUS'  => \Bitrix\Sale\Cashbox\Check::CHECK_STATUS_ERROR,
        '>=DATE_CREATE' => new \Bitrix\Main\Type\DateTime('-1 hour'),
    ],
]);

foreach ($checks as $check) {
    if ($check['TYPE'] === \Bitrix\Sale\Cashbox\SellReturnCheck::TYPE) {
        NotificationService::alertAdmin(
            'Помилка чека повернення #' . $check['ID'] . ': ' . $check['ERROR']
        );
    }
}

Склад робіт

• Перевірка версії модуля sale.cashbox та сумісності з версією касового оператора
• Налаштування обробника каси для середовища повернень (тестовий/бойовий URL)
• Тестування всіх сценаріїв повернень у тестовому середовищі оператора
• Налаштування агента моніторингу помилок фіскалізації
• Перевірка коректності ПДВ у позиціях замовлення та повернення
• Документація щодо ручного пробиття чека у нештатних ситуаціях

Терміни: якщо каса вже налаштована для чеків приходу — налаштування повернень займає 1–2 тижні. Якщо каса налаштовується з нуля — 3–5 тижнів, включаючи тестування в усіх сценаріях.