Catcode PRRO Connector — фіскалізація чеків (Вчасно.Каса, Checkbox) для WooCommerce

Catcode PRRO Connector — плагін фіскалізації для WooCommerce, який зв’язує магазин з українськими програмними РРО і пробиває фіскальний чек автоматично, щойно замовлення переходить у заданий статус (наприклад, «processing» після оплати LiqPay чи Monobank). Один плагін покриває кілька ПРРО-сервісів з fallback між ними, керує зміною каси і сам надсилає чек покупцю на email та SMS.

Підтримувані ПРРО

• Вчасно.Каса — повна підтримка: чеки продажу, керування зміною, перевірка зв’язку.
• Checkbox — адаптер за публічною документацією API.

Можна призначити основний сервіс і резервний (fallback): якщо основний не відповідає, чек автоматично йде через запасний.

Як це працює — крок за кроком

1. Покупець оплачує замовлення через будь-яку платіжку — LiqPay, Monobank, WayForPay тощо.
2. Платіжка переводить замовлення у статус «processing» своїм callback-ом.
3. Плагін ловить зміну статусу (woocommerce_order_status_changed) і надсилає дані чека у ПРРО; якщо зміна каси закрита — спершу відкриває її і повторює чек.
4. ПРРО повертає фіскальний номер — він пишеться у нотатку замовлення та в журнал чеків.
5. Покупець отримує чек: email з посиланням на PDF і, за бажанням, SMS через TurboSMS.
6. Бухгалтерія забирає журнал чеків із PDF/HTML-посиланнями через CSV-експорт.

Окремо: кнопка «Пробити чек» на сторінці замовлення, список методів оплати, які фіскалізуються як готівка (післяплати Нової Пошти, Укрпошти), доставка у чеку, пропуск нульових позицій, УКТЗЕД-код на кожен товар + дефолтний код.

Джерело KeyCRM

З версії 0.5.0 плагін фіскалізує не лише замовлення WooCommerce: він тягне оплачені замовлення з KeyCRM (агрегатор Rozetka, Prom, Instagram і власних сайтів) і пробиває для них чеки через ті самі ПРРО-сервіси. Меню «Каса → Замовлення KeyCRM»: API-ключ, інтервал опитування, тригер, журнал запусків, опційний запис посилання на чек назад у замовлення KeyCRM. Кожне замовлення фіскалізується рівно один раз.

Офлайн-продажі з каси Checkbox → залишки на сайті (Pro)

Магазин із точкою продажу й сайтом продає одну полицю двічі. Куртку пробили на касі годину тому, а сайт і далі показує її в наявності — власник дізнається про це, коли онлайн-покупець уже заплатив. З версії 1.2.0 Pro закриває цю дірку: кожен фіскалізований чек на касі Checkbox у магазині списує той самий товар із залишку WooCommerce, а чек повернення повертає його назад.

1. У Checkbox код товару дорівнює артикулу (SKU) товару або варіації на сайті. Якщо код інший — плагін шукає за штрихкодом: як артикул і як GTIN/EAN.
2. На екрані «Каса → Офлайн-продажі» вкажіть логін і пароль касира та ключ ліцензії каси магазину (або залиште поля порожніми, якщо це та сама каса, що на вкладці Checkbox) і натисніть «Підключити вебхук». Адресу сайту в Checkbox плагін реєструє сам.
3. Далі Checkbox після кожного чека надсилає його на сайт. Плагін перевіряє підпис ключем, який видав Checkbox, бере лише фіскалізовані продажі й повернення і змінює залишок.

Чеки, які сайт сам пробив для онлайн-замовлень, пропускаються — WooCommerce уже списав для них залишок. Checkbox повторює доставку кілька годин, але той самий чек вдруге нічого не змінює, навіть якщо копії прийшли одночасно. Товар, якого не знайдено, або товар без обліку залишку видно в журналі окремим рядком — одразу зрозуміло, який код у касі виправити.

Що під капотом

• API-ключі й паролі шифруються у БД — sodium_crypto_secretbox, з фолбеком на HMAC-потоковий шифр, коли розширення libsodium недоступне. Секрети не виводяться назад у HTML форм.
• Архітектура адаптерів: спільний інтерфейс провайдера + окремий адаптер на кожен ПРРО-сервіс, ланцюжок основний → fallback.
• Захист від дублів — фіскальний номер звіряється через БД, повтор зафейлених чеків не створює другий чек; купони враховано так, щоб sum(позицій) збігалася з total.
• Телефон покупця нормалізується до E.164 (+380…) перед відправкою у ПРРО.
• Хук catcodeprro_after_fiscalize — для власних інтеграцій після успішного чека.

Як встановити

1. Встановіть плагін із каталогу WordPress.org або завантажте zip-архів через «Плагіни → Додати новий → Завантажити плагін» і активуйте.
2. Меню «Каса → Налаштування» → вкладка Вчасно.Каса: введіть API-ключ і фіскальний номер ПРРО з кабінету Вчасно.
3. Натисніть «Зберегти і перевірити звʼязок» — зʼявиться повідомлення, що зʼєднання з Вчасно.Каса працює.
4. На вкладці сервісу оберіть роль «Основна каса», а на вкладці «Чеки» увімкніть «Автоматичне пробивання».
5. Перевірте на копійчаному замовленні через «Каса → Тест» → «Пробити чек».
6. У «Каса → Чеки» з’явиться рядок «успішно» з реальним фіскальним номером — готово.