Чеки
Где шлюз умеет пробить чек сам — он его и бьёт. Для всех остальных путей прихода денег — наличные курьеру, перевод на счёт, счёт юрлицу, подтверждение офлайнового платежа менеджером, наложенный платёж от перевозчика — есть драйвер кассы с очередью документов и ключом идемпотентности.
В коробке две кассы:
| Ключ | Касса | Где |
|---|---|---|
atol | АТОЛ Онлайн v4 | Россия, 54‑ФЗ |
checkbox | Checkbox | Украина, ПРРО |
Сайт может зарегистрировать свою через fiscal_drivers в core/App/config/pbshop.php: слой — это интерфейс и реестр, а новая касса — карта полей поверх Support\Receipt.
Касса одна на магазин, выбирается pbshop_fiscal_driver. Пусто — фискализации нет вовсе, и это умолчание: магазин за пределами России и Украины чек бить не должен, а включённая по умолчанию касса слала бы документы в никуда на каждой оплате.
Настройки кассы — системные настройки MODX, а не свойства способа
В отличие от платёжных драйверов. Довод не вкусовой: договор с ОФД у магазина один на всё юрлицо, и касса одна на все способы оплаты. Положи её реквизиты на способ — и ИНН с адресом расчётов пришлось бы дублировать в каждую строку способа, а разойдясь однажды, они дали бы чеки от двух разных продавцов.
Что нужно АТОЛу
Все они — системные настройки pbshop_fiscal_*:
| Настройка | Что это |
|---|---|
driver | atol |
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 (ПРРО)
| Настройка | Что это |
|---|---|
driver | checkbox |
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 — отказ по существу. Не повторяется.
В строке лежат операция (приход или возврат), сумма и валюта, число попыток, сырой обмен и те номера, которые нужны налоговой: номер фискального документа, фискальный признак, номер фискального накопителя, номер смены и время пробития.
Менеджер видит всё это в своём гриде Чеки, а чек или отказ пишется ещё и в ленту истории заказа.
Добор недопечатанных
Уведомление кассы может не дойти вовсе — сайт лежал, адрес сменился, касса не стала повторять. Единственный надёжный способ узнать исход — спросить самим.
$modx->services->get('pbshop')->fiscal()->poll();Это на крон сайта, раз в несколько минут: чек печатается не мгновенно. Метод берёт незаконченные строки, у которых попытки не исчерпаны и которые не трогали слишком недавно, отправляет или дочитывает каждую и возвращает число обработанных. См. Подписки и крон — это одна из трёх задач, чьё молчание считается критичным.
Checkbox асинхронна с обоих концов: смена отвечает 202 и открывается через секунды, чек отвечает 201 со статусом «создан». Драйвер не крутит опрос внутри колбэка платежа — это были бы секунды в чужом HTTP-запросе. «Ещё не готово» возвращается как повторяемое, и строку добирает крон. Платёж при этом уже признан: покупатель не должен терять деньги из-за того, что касса не ответила.
Телу уведомления не верит ни один из двух, даже когда оно подписано. Checkbox уведомления подписывает, и подпись проверяется, — но исход всё равно читается из API, потому что подпись доказывает, кто писал, а не то, что документ в этом состоянии.
Чего здесь нет
- Чека при частичном возврате. Намеренно: чек возврата обязан назвать товары поимённо, а у частичного возврата состава нет — только сумма.
- Касс, кроме этих двух. Слой готов, а драйвер — карта полей; Бизнес.ру, Модуль и Комтет по спросу.
Ни одна из двух касс не пробила настоящего чека
Живой кассы у нас нет, как нет и живого шлюза: договор с ОФД не заключишь ради проверки, а песочница АТОЛа выдаётся вместе с ним.
Разница, которую стоит знать: у АТОЛа адрес, формат времени, коды форм оплаты и список ставок выписаны из рабочего клиента, а не из пересказа документации. Checkbox написана по её OpenAPI и вики, и песочницы у Checkbox нет вовсе — тестируют тестовым кассиром на том же боевом адресе. Планируйте свой первый чек соответственно.
Дальше
- Оплата — какие шлюзы фискализируют сами
- Что где лежит — честная табличка статуса