REST: касса и чеки (54-ФЗ)

Группа sale.cashbox.* в REST API Битрикс24 отвечает за фискализацию по 54-ФЗ: подключение онлайн-кассы, формирование и печать чеков прихода и возврата, передачу признаков предмета и способа расчёта. Через REST-обработчик кассы можно интегрировать облачный сервис фискализации без модуля на портале.

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

Касса в Битрикс24 — это сущность, которая по событиям оплаты и отгрузки формирует фискальные чеки и отправляет их оператору фискальных данных (ОФД). Через REST доступны как подключение кассы, так и собственный обработчик:

• sale.cashbox.add / update / list / delete — управление кассами;
• sale.cashbox.handler.add — регистрация REST-обработчика кассы;
• sale.cashbox.check.* — работа с чеками;
• sale.cashbox.checkType.* — типы чеков (приход, возврат прихода и т.д.).

REST-обработчик кассы

Собственный сервис фискализации регистрируется методом sale.cashbox.handler.add. В настройках описываются поля подключения (адрес API, токен, система налогообложения) и URL, куда портал будет слать задания на печать чека:

sale.cashbox.handler.add { "CODE": "my_ofd", "NAME": "Моя онлайн-касса", "SETTINGS": { "PRINT_URL": "https://app.example.com/kkm/print/", "CHECK_URL": "https://app.example.com/kkm/check/", "CONFIG": { "AUTH": { "LABEL": "Токен ОФД", "ITEMS": { "TOKEN": { "TYPE": "STRING" } } } } } }

Затем создаётся касса через sale.cashbox.add с указанием этого обработчика. Одна касса может обслуживать заказы конкретных платёжных систем.

Печать чека и обратный статус

Когда наступает момент фискализации (оплата или отгрузка — в зависимости от настроек), Битрикс24 отправляет на PRINT_URL задание с составом чека. Приложение печатает чек в ОФД и возвращает результат методом sale.cashbox.check.apply:

1. портал шлёт задание на печать со списком позиций, сумм и признаков расчёта;
2. приложение отправляет чек в кассу или ОФД и получает фискальные реквизиты;
3. результат возвращается через sale.cashbox.check.apply с фискальным признаком и ссылкой на чек либо фиксируется ошибка.

Признаки предмета и способа расчёта

54-ФЗ требует указывать для каждой позиции признак предмета расчёта (товар, услуга, платёж) и признак способа расчёта (полная оплата, аванс, предоплата). В задании на печать эти значения приходят по позициям, и их важно корректно замапить на коды вашего ОФД.

Ставка НДС берётся из настроек товара каталога (catalog.vat.*) и системы налогообложения кассы. Ошибки в этих признаках — частая причина отказа ОФД, поэтому маппинг проверяют на тестовых чеках. Отдельно приходит признак способа оплаты (наличные, безналичные, предоплата, зачёт аванса) — его тоже нужно передать в ОФД. Для маркированных товаров в позиции добавляется код маркировки, и приложение обязано передать его в чек, иначе фискализация не пройдёт.

Возвраты и типы чеков

Помимо чека прихода касса формирует чек возврата прихода. Тип чека определяется через sale.cashbox.checkType.*, а сам возврат инициируется при отмене оплаты или оформлении возврата в заказе. Приложение должно поддерживать оба сценария:

• приход — при оплате заказа;
• возврат прихода — при возврате средств покупателю;
• коррекционные чеки — при расхождениях, если их поддерживает ваш ОФД.

Историю и состояние чеков по заказу можно получить через sale.cashbox.check.get и sale.cashbox.check.list. Важно, что возврат прихода привязывается к исходному чеку: в задании на печать возвратного чека приходят реквизиты первичного, чтобы ОФД корректно провёл операцию. Если исходный чек пробивался авансом, а окончательный расчёт — при отгрузке, возврат тоже должен учитывать эту схему, иначе кассовая дисциплина по 54-ФЗ будет нарушена.

Практика подключения

Надёжная интеграция кассы строится по шагам:

1. регистрируем обработчик sale.cashbox.handler.add и тестируем на демо-ОФД;
2. создаём кассу sale.cashbox.add и привязываем к платёжным системам;
3. отрабатываем печать: приём задания, отправка в ОФД, подтверждение sale.cashbox.check.apply;
4. добавляем возвраты и обработку ошибок ОФД с повторными попытками;
5. логируем каждый чек с фискальным признаком для сверки.

Итог

Через REST-обработчик sale.cashbox.* к Битрикс24 подключается любой сервис фискализации по 54-ФЗ: касса регистрируется, принимает задания на печать, отправляет чеки в ОФД и подтверждает результат через sale.cashbox.check.apply. Ключевые тонкости — корректные признаки предмета и способа расчёта, ставки НДС, поддержка возвратов и асинхронное подтверждение фискализации.

Мы подключаем онлайн-кассы и облачную фискализацию к CRM-магазину Битрикс24, настраиваем маппинг признаков расчёта и обработку ошибок ОФД, а затем сопровождаем интеграцию. Если нужна фискализация заказов по 54-ФЗ без ручной возни — поможем внедрить её корректно.