Skip to content

Чеки ​

Где шлюз умеет пробить чек сам — он его и бьёт. Для всех остальных путей прихода денег — наличные курьеру, перевод на счёт, счёт юрлицу, подтверждение офлайнового платежа менеджером, наложенный платёж от перевозчика — есть драйвер кассы с очередью документов и ключом идемпотентности.

В коробке две кассы:

КлючКассаГде
atolАТОЛ Онлайн v4Россия, 54‑ФЗ
checkboxCheckboxУкраина, ПРРО

Сайт может зарегистрировать свою через fiscal_drivers в core/App/config/pbshop.php: слой — это интерфейс и реестр, а новая касса — карта полей поверх Support\Receipt.

Касса одна на магазин, выбирается pbshop_fiscal_driver. Пусто — фискализации нет вовсе, и это умолчание: магазин за пределами России и Украины чек бить не должен, а включённая по умолчанию касса слала бы документы в никуда на каждой оплате.

Настройки кассы — системные настройки MODX, а не свойства способа

В отличие от платёжных драйверов. Довод не вкусовой: договор с ОФД у магазина один на всё юрлицо, и касса одна на все способы оплаты. Положи её реквизиты на способ — и ИНН с адресом расчётов пришлось бы дублировать в каждую строку способа, а разойдясь однажды, они дали бы чеки от двух разных продавцов.

Что нужно АТОЛу ​

Все они — системные настройки pbshop_fiscal_*:

НастройкаЧто это
driveratol
login, passwordдоступы кабинета АТОЛа
groupкод группы из кабинета
innИНН продавца
addressадрес расчётов: для интернет-магазина это адрес сайта. Пусто — возьмётся адрес сайта, но лучше назвать явно: он печатается в чеке
snoсистема налогообложения: osn, usn_income, usn_income_outcome, envd, esn, patent. По умолчанию usn_income
emailпочта продавца, печатается в чеке
vat_codeставка по умолчанию, 1 — без НДС. У товара своя ставка задаётся полем конструктора и главнее
currencyвалюта, в которой бьются чеки, по умолчанию RUB
test_modeтестовый контур кассы

Что нужно Checkbox (ПРРО) ​

НастройкаЧто это
drivercheckbox
login, passwordдоступы кассира, а не кабинета
pinвход по пин-коду вместо логина; требует ключа лицензии
licence_keyключ лицензии кассы. Обязателен в любом случае — без него не открыть смену, а без открытой смены ПРРО не примет ни одного чека
cashier_nameимя кассира в чеке; пусто — подставит касса
departamentотдел, строкой. Пишется с опечаткой самой кассы, иначе она поля не увидит
shift_hoursчерез сколько часов касса закроет смену сама. По умолчанию 23
tax_codesкарта «код ставки pbShop → код ставки кассы», JSON
smsотправлять чек в SMS. Выключено: у Checkbox это платная услуга, и без неё касса отказала бы на каждом чеке
currencyобязан быть UAH — иначе ядро до кассы не дойдёт вовсе

Два умолчания здесь не те, что можно предположить

shift_hours обязан остаться меньше суток. Фискальное действие в смене, открытой дольше, ПРРО отвергает целиком, а закрывать её в магазине некому: менеджер про смены не знает.

tax_codes пусто — то есть ставка не передаётся вовсе, и касса применяет настроенную у позиции сама. Это верное умолчание для ФОПа на едином налоге без ПДВ и единственное безопасное вообще: коды ставок у ПРРО — настройка организации в её кабинете, а не справочник закона, и с нумерацией полей pbShop они не совпадают ничем.

И ещё: pbshop_fiscal_currency по-прежнему по умолчанию RUB. Оно не переехало на UAH вместе с приездом ПРРО намеренно — это перевело бы уже установленные рублёвые магазины на «чеков не бьём» молча. Задайте явно.

Никогда дважды ​

Повторная фискализация той же оплаты — это разговор с налоговой, а не запись в логе, и отозвать лишний фискальный документ нельзя. Поэтому защита трёхслойная, и слои отвечают за разное.

Ядро не даёт завести вторую строку чека на одну оплату — уникальный индекс на номере документа — и не даёт двум процессам одновременно позвать кассу по одной строке.

Номер документа вычисляется, а не хранится: UUID v5 от внешнего идентификатора. Это важно именно на аварии. Упади процесс между отправкой и сохранением — следующий заход придёт с тем же номером, касса ответит «уже принято», и магазин перечитает её ответ вместо того, чтобы пробить второй чек. Со случайным номером касса сочла бы повтор новым документом.

«Уже существует» — это ответ, а не ошибка. Сам документ касса при этом не возвращает, поэтому его надо перечитать. Отнестись к этому ответу как к отказу значило бы считать пробитый чек непробитым.

Случай, который выглядит парадоксом

Если касса отвергла документ по существу, номер сожжён: фискального чека по нему нет и не будет, но и принять его повторно касса откажется.

Поэтому после отказа берётся следующий номер — и берётся он только после того, как касса подтвердила отказ чтением. Без этого условия «взять новый номер» означало бы «пробить второй чек»; с ним — «повторить документ, которого у кассы нет».

А там, где шлюз фискализирует сам, касса пропускается целиком: у драйвера спрашивают, умеет ли он это, и если умеет — второго чека не заводят.

Очередь и её состояния ​

Чеки живут в pb_shop_receipts, по строке на документ, и строка не удаляется никогда: фискальный документ существует в налоговой независимо от этой базы.

new  →  pending  →  done
                 ↘  failed
  • new — ещё не отправлен либо отправка сорвалась так, что стоит повторить;
  • pending — касса приняла, номера ещё не приехали;
  • done — пробит, номера в строке;
  • failed — отказ по существу. Не повторяется.

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

Менеджер видит всё это в своём гриде Чеки, а чек или отказ пишется ещё и в ленту истории заказа.

Добор недопечатанных ​

Уведомление кассы может не дойти вовсе — сайт лежал, адрес сменился, касса не стала повторять. Единственный надёжный способ узнать исход — спросить самим.

php
$modx->services->get('pbshop')->fiscal()->poll();

Это на крон сайта, раз в несколько минут: чек печатается не мгновенно. Метод берёт незаконченные строки, у которых попытки не исчерпаны и которые не трогали слишком недавно, отправляет или дочитывает каждую и возвращает число обработанных. См. Подписки и крон — это одна из трёх задач, чьё молчание считается критичным.

Checkbox асинхронна с обоих концов: смена отвечает 202 и открывается через секунды, чек отвечает 201 со статусом «создан». Драйвер не крутит опрос внутри колбэка платежа — это были бы секунды в чужом HTTP-запросе. «Ещё не готово» возвращается как повторяемое, и строку добирает крон. Платёж при этом уже признан: покупатель не должен терять деньги из-за того, что касса не ответила.

Телу уведомления не верит ни один из двух, даже когда оно подписано. Checkbox уведомления подписывает, и подпись проверяется, — но исход всё равно читается из API, потому что подпись доказывает, кто писал, а не то, что документ в этом состоянии.

Чего здесь нет ​

  • Чека при частичном возврате. Намеренно: чек возврата обязан назвать товары поимённо, а у частичного возврата состава нет — только сумма.
  • Касс, кроме этих двух. Слой готов, а драйвер — карта полей; Бизнес.ру, Модуль и Комтет по спросу.

Ни одна из двух касс не пробила настоящего чека

Живой кассы у нас нет, как нет и живого шлюза: договор с ОФД не заключишь ради проверки, а песочница АТОЛа выдаётся вместе с ним.

Разница, которую стоит знать: у АТОЛа адрес, формат времени, коды форм оплаты и список ставок выписаны из рабочего клиента, а не из пересказа документации. Checkbox написана по её OpenAPI и вики, и песочницы у Checkbox нет вовсе — тестируют тестовым кассиром на том же боевом адресе. Планируйте свой первый чек соответственно.

Дальше ​

pbShop — магазин для сайтов на PageBlocks