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

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

Плагін повністю безкоштовний. Завантажити: каталог WordPress.org.

Що отримує адмін

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

• Вчасно.Каса — повна підтримка: чеки продажу, керування зміною, перевірка зв’язку.
• 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. Кожне замовлення фіскалізується рівно один раз.

Що входить у безкоштовну версію, а що в Pro

Фіскалізація як така — безкоштовна й лишається такою: автоматичний чек за статусом замовлення, два сервіси з резервним перемиканням, зміни за розкладом, журнал чеків, лист і SMS покупцю, тестовий режим. Це те, що вже роздано в каталозі WordPress.org, і воно нікуди не переїжджає.

Pro-ліцензія додає те, що потрібно магазину, коли починаються повернення:

• Чек повернення на кожне часткове повернення. Повернули одну позицію з трьох, тільки доставку або довільну суму — плагін пробиває окремий чек рівно на те, що повернулось, і привʼязує його до чека продажу.
• Повернення через API Вчасно.Каса. Без Pro такий чек доводиться пробивати руками в кабінеті сервісу.
• Повтор чека з журналу. Каса була недоступна чи зміна закрилась — одна кнопка на рядку або «повторити всі невдалі». Уже пробитий чек повторно в ПРРО не піде.
• Звірка змін. Кожен Z-звіт проти суми чеків із журналу (продажі мінус повернення) і підсвічена розбіжність — саме те місце, де видно чек, пробитий повз магазин.

Скільки коштує

Безкоштовна версія — 0 грн, назавжди й без реєстрації. Pro — 1490 грн на рік за один домен: рік оновлень і підтримки. Перед покупкою можна ввімкнути 7-денний пробний період прямо в адмінці — без картки й без автопродовження.

Технічні вимоги

• WordPress 6.4+ / WooCommerce 8.0+ (HPOS-сумісність, протестовано до WC 10.7)
• PHP 7.4+
• Зареєстрований ПРРО у податковій — через кабінет обраного сервісу (Вчасно.Каса, Checkbox)
• API-ключ з кабінету ПРРО-сервісу і налаштована там ставка ПДВ

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

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

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

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

Історія версій

1.1.0 — серпень 2026

Зʼявився Pro-рівень, безкоштовна частина не змінилась. Pro: чек повернення на кожне повернення WooCommerce, включно з частковим і з довільною сумою; повернення через API Вчасно.Каса замість ручного чека в кабінеті; повтор одного або всіх невдалих чеків прямо з журналу; звірка змін — Z-звіт проти суми чеків. Повторна фіскалізація тепер ідемпотентна: чек, який уже пройшов, вдруге в ПРРО не відправляється.

1.0.2 — серпень 2026

Оновлення зі збірок до 1.0.0 тепер переносить журнал чеків, журнал змін і мапу замовлень KeyCRM у перейменовані таблиці. Без цього після оновлення журнали виглядали порожніми, а захист від дублю читає саме таблицю чеків — тобто замовлення з уже пробитим чеком могло отримати другий фіскальний чек. Видалення плагіна тепер прибирає власні таблиці (в обробнику лишались їхні старі імена). Внутрішня константа версії застрягла на 1.0.0, через що процедура оновлення не запускалась.

1.0.1 — серпень 2026

Оновлений український переклад, статуси змін на екрані «Зміни» стали перекладними.

1.0.0 — серпень 2026

Перший публічний реліз у каталозі WordPress.org.

0.5.3 — липень 2026

Екранування всього виводу: посилання на чек і додатковий текст у plain-text листі, згенеровані елементи форм і бейджі на сторінці налаштувань (wp_kses з явним переліком дозволених тегів). Санітизація API-ключа KeyCRM на читанні, англомовний readme для каталогу WordPress.org.

0.5.2 — липень 2026

Єдиний префікс catcodeprro_ для всіх опцій, хуків, мета-полів і таблиць. Стилі та скрипти адмінки винесено в assets/ і підключено через wp_enqueue_*. Прибрано неробочі адаптери Cashalot/SmartPOS. Плагін перейменовано на «Catcode PRRO Connector».

0.5.0 — липень 2026

Вбудоване джерело KeyCRM: фіскалізація оплачених замовлень з Rozetka/Prom/Instagram через KeyCRM Open API (меню «Каса → KeyCRM»). Кожне замовлення фіскалізується рівно один раз; журнал запусків; ліміт 60 req/хв і обробка 429.

0.4.0 — 2026

Новий екран налаштувань: один майстер замість вкладок, статус-блок «працює / потребує уваги», кнопка «Зберегти і перевірити зв’язок». Fix базового URL Checkbox API (api.checkbox.in.ua); Checkbox повернуто у розширені налаштування.

0.3.x — 2026

Автоматичне керування зміною каси за розкладом (cron двічі на добу), авто-відкриття зміни при чеку, ручні кнопки на сторінці «Зміни». Вкладки налаштувань, захист секретів у формах, фікси логера.

0.2.x — 2026

Реальні endpoint-и Вчасно.Каса, фікс купонів (sum(items) == total), захист від дублів чеків, УКТЗЕД-коди, нормалізація телефону, кнопка «Пробити чек», CSV-експорт, email-шаблон чека, TurboSMS.

0.1.0 — 2026

Перший реліз: 4 адаптери ПРРО і базова автофіскалізація при зміні статусу замовлення.