=== Multi PRRO Connector ===
Contributors: catcode
Tags: woocommerce, fiscalization, vchasno, checkbox, prro, ukraine
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 0.5.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Інтеграція WooCommerce з українськими ПРРО (програмними РРО): Вчасно.Каса і Checkbox. Автоматичне пробивання фіскальних чеків при зміні статусу замовлення.

== Опис ==

Плагін зв'язує WooCommerce з програмними РРО (ПРРО). Підтримує:

* **Вчасно.Каса** — повноцінно (POST /api/v1/orders, токен з кабінету)
* **Checkbox** — написано за публічною документацією, потребує перевірки на живому акаунті

Резервний (fallback) сервіс підставляється автоматично якщо основний не відповідає — корисно для високонавантажених магазинів.

= Можливості =

* Автоматичне пробивання чеку при переході замовлення у вибраний статус (зазвичай "processing" після оплати LiqPay/Monobank/тощо)
* Кнопка "Пробити чек" на сторінці кожного замовлення
* Журнал чеків з PDF/HTML посиланнями і CSV-експортом для бухгалтерії
* Шифрування ключів API і паролів у БД (libsodium)
* Налаштовуваний список способів оплати які трактуються як готівка (для UA Shipping післяплат, Нова Пошта, Укрпошта)
* УКТЗЕД код товару — поле в редакторі WooCommerce продукту + дефолт для всіх товарів
* Нормалізація номера телефону покупця до E.164 (+380...)
* Опція "Включати/не включати доставку у чек"
* Опція "Пропускати товари з 0 грн"
* Email-сповіщення покупцю через WC email template з посиланням на PDF чеку
* SMS-сповіщення (TurboSMS), опційно
* HTML-хук `mpc_after_fiscalize` для сторонніх інтеграцій
* HPOS-сумісність

= Вимоги =

* WooCommerce 8.0 або новіше
* PHP 8.0+
* Зареєстрований ПРРО в податковій (через кабінет вибраного сервісу)
* Відкрита зміна на ПРРО

= Як це працює =

1. Клієнт оплачує замовлення (через будь-яку платіжку — LiqPay, Monobank, WayForPay, тощо)
2. Платіжка переводить замовлення WooCommerce у статус "processing" через свій callback
3. Плагін слухає `woocommerce_order_status_changed` і запускає фіскалізацію
4. У ПРРО надсилається POST з даними чеку, плагін отримує фіскальний номер
5. Покупець отримує email з PDF чеку, у замовлення додається нота з ID

Сума у чек йде ПОВНА (як на замовленні) — а не "сума мінус комісія еквайєра". Це відповідає ЗУ "Про РРО": фіскальний чек має відображати суму яку сплатив покупець.

== Встановлення ==

1. Залити папку плагіна у `/wp-content/plugins/multi-prro-connector/`
2. Активувати у меню "Плагіни"
3. Меню "Каса" → Налаштування → вкладка Вчасно.Каса
4. Ввести API-ключ і фіскальний номер ПРРО (з кабінету Вчасно)
5. Натиснути "Перевірити звʼязок" — має написати OK
6. Вкладка "Загальне" → Основний сервіс = Вчасно.Каса, Автоматично пробивати чеки = увімкнути
7. Перейти на меню "Каса → Тест" → ввести ID копійчаного замовлення → "Пробити чек"
8. Подивитися на сторінці "Каса → Чеки" — має зʼявитися рядок зі статусом "успішно" і реальним фіскальним номером

== Часті питання ==

= Що потрібно у Вчасно.Касі перед використанням? =

Зареєструвати ПРРО у податковій (через кабінет Вчасно), налаштувати ставку ПДВ для нього (без ПДВ для ФОП на ЄП або 20% для платників ПДВ), відкрити зміну. Без відкритої зміни API віддасть помилку.

= Чи можна повертати чеки через плагін? =

Поки що для Вчасно — ні. Повернення робиться вручну в кабінеті Вчасно. Замовлення зі статусом "refunded" отримає нейтральну ноту з нагадуванням.

= Хто керує ПДВ-ставкою чеку? =

Для Вчасно — кабінет ПРРО (на сторні Вчасно). У payload плагіна ПДВ не передається. Для Checkbox/Cashalot — можна вказати УКТЗЕД код у редакторі товару.

= Джерело KeyCRM (нове у 0.5.0) =

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

== Changelog ==

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

= 0.4.0 =
* Повністю новий екран налаштувань: один зрозумілий майстер замість вкладок
* Великий статус-блок (працює / потребує уваги), пронумеровані кроки, людська мова
* Технічні опції сховані у згорнутий розділ «Розширені налаштування»
* Каса Вчасно вмикається автоматично після введення ключа — без зайвих перемикачів
* Кнопка «Зберегти і перевірити звʼязок» в один клік
* Fix: правильний базовий URL Checkbox API (api.checkbox.in.ua)
* Checkbox знову доступний (у розширених) — статус перевіряється кнопкою, без дисклеймерів

= 0.3.1 =
* Сторінку налаштувань розбито на вкладки: Загальне, Чек, Зміна каси, Сповіщення, Вчасно.Каса, Checkbox
* Захист секретів: API-ключі/паролі не виводяться у HTML, порожнє поле більше не затирає збережене значення
* Fix: логування закриття зміни падало через NOT NULL на opened_at
* Оновлено опис плагіна і застарілі підказки

= 0.3.0 =
* Автоматичне керування зміною каси: відкриття/закриття за розкладом через /api/v3/fiscal/execute (task 0/11)
* Cron 2 рази на добу (час налаштовується, типово 00:01 відкриття, 23:59 закриття зі звітом)
* Автовідкриття зміни при чеку: якщо зміна закрита коли прийшло замовлення — плагін відкриває зміну і повторює чек
* Ручні кнопки відкрити/закрити зміну на сторінці «Зміни»
* Реальні open_shift/close_shift у VchasnoAdapter (раніше були заглушки)

= 0.2.1 =
* Cleanup: знято з UI Cashalot/SmartPos (нефункціональні адаптери, залишаться у кодовій базі для майбутнього рефакторингу)
* Fix: AbstractAdapter — wp_remote_request падав на stdClass body у WP 6.x

= 0.2.0 =
* Реальні endpoints VchasnoAdapter (POST /api/v1/orders з rro_fn/tag/goods/total_sum/payment_type)
* Виправлено критичний баг з купонами: sum(items) == total
* Виправлено retry зафейлених чеків (Logger тепер upsert)
* Виправлено дублі чеків при порожньому fiscal_id (перевірка через БД)
* УКТЗЕД код товару + дефолт у налаштуваннях
* Нормалізація телефону до +380...
* Налаштовуваний список готівкових платежів (UA Shipping)
* Кнопка "Пробити чек" на сторінці замовлення
* Опції "Пропускати товари з 0 грн" і "Включати доставку у чек"
* CSV-експорт чеків + Bulk-відкриття PDF
* WC email template для чеку покупцю
* Хук mpc_after_fiscalize для сторонніх інтеграцій
* TurboSMS стартер
* Settings cache + autoload=yes
* Vchasno returns — нейтральна нота замість червоного error
* Український UI з тултипами

= 0.1.0 =
* Перший реліз з 4 адаптерами і базовою auto-фіскалізацією.
