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

Automatic WooCommerce fiscal receipts through Ukrainian software cash registers (PRRO): Vchasno.Kasa and Checkbox.

== Description ==

The plugin connects WooCommerce to Ukrainian software cash registers (PRRO), so a paid order is fiscalised without anyone opening the provider's dashboard. Supported providers:

* **Vchasno.Kasa** — full support (POST /api/v1/orders, token from the provider dashboard)
* **Checkbox** — implemented from the public documentation

A fallback provider takes over automatically when the primary one does not answer, which keeps receipts flowing on busy shops.

The plugin interface is Ukrainian, because that is the language of the shops these cash registers serve.

= Features =

* Receipt is issued automatically when an order reaches the selected status (usually "processing" after payment)
* "Issue receipt" button on every order screen
* Receipt log with PDF/HTML links and CSV export for the accountant
* API keys and passwords are encrypted in the database (libsodium)
* Configurable list of payment methods treated as cash (for cash-on-delivery shipping methods)
* UKTZED product code — a field in the WooCommerce product editor plus a shop-wide default
* Customer phone normalised to E.164 (+380…)
* Options to include shipping in the receipt and to skip zero-price items
* Customer email with the receipt PDF link, sent through a WooCommerce email template
* Optional SMS delivery of the receipt link (TurboSMS)
* `catcodeprro_after_fiscalize` hook for third-party integrations
* HPOS compatible

= Requirements =

* WooCommerce 8.0 or newer
* PHP 8.0+
* A PRRO registered with the Ukrainian tax authority through your provider's dashboard
* An open cash register shift

= How it works =

1. The customer pays for the order through any payment gateway.
2. The gateway moves the WooCommerce order to "processing" via its callback.
3. The plugin listens to `woocommerce_order_status_changed` and starts fiscalisation.
4. The receipt payload is sent to the cash register and the fiscal number comes back.
5. The customer receives an email with the receipt PDF; the fiscal id is added to the order notes.

The receipt always carries the full order total the customer paid, not the total minus an acquirer fee — that is what Ukrainian cash register law requires.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/catcode-prro-connector/`.
2. Activate it on the Plugins screen.
3. Open the "Каса" menu → Settings → the Vchasno.Kasa tab.
4. Enter the API key and the fiscal number of your cash register.
5. Press "Save and test connection" — it should report success.
6. Turn on automatic fiscalisation on the "Чеки" tab.
7. Issue a receipt for a small test order and check the "Чеки" screen: the row must show a real fiscal number.

== Frequently Asked Questions ==

= What has to be ready on the provider side? =

Register the PRRO with the tax authority through your provider's dashboard, set its VAT rate, and open a shift. Without an open shift the API returns an error.

= Can the plugin issue refund receipts? =

Not for Vchasno yet — refunds are done in the provider dashboard. An order moved to "refunded" gets a neutral order note as a reminder.

= What controls the VAT rate on the receipt? =

For Vchasno it is the cash register configuration on the provider side; the plugin does not send a VAT rate. For Checkbox you can set the UKTZED code per product.

= Can it fiscalise orders that are not WooCommerce orders? =

Yes. The optional KeyCRM source pulls paid orders from [KeyCRM](https://keycrm.app) (an aggregator for Rozetka, Prom, Instagram and custom sites) and issues receipts for them through the same cash registers: API key, polling interval, trigger statuses, a run log and an optional receipt link written back to the KeyCRM order.

== External services ==

This plugin sends order data to third-party fiscalisation providers. Data is only sent to a provider you have explicitly configured with your own API credentials.

**Vchasno.Kasa** — Ukrainian software cash register (PRRO). Used to register fiscal receipts. When a receipt is issued the plugin sends the order total, line items, payment type, cash register ID and, if receipt delivery is enabled, the customer email/phone to `https://kasa.vchasno.ua`. Terms: https://help.vchasno.com.ua/oferty/ · Privacy: https://help.vchasno.com.ua/privacypolicy/

**Checkbox** — Ukrainian software cash register (PRRO). Same receipt data is sent to `https://api.checkbox.in.ua` when Checkbox is selected as a provider. Terms and privacy policy: https://checkbox.ua/oferta/

**KeyCRM** — optional order source. If enabled, the plugin polls `https://openapi.keycrm.app/v1` for paid orders (order id, status, buyer contacts, line items) so they can be fiscalised, and may write the receipt link back to the order. Terms: https://keycrm.app/terms-of-use · Privacy: https://keycrm.app/privacy-policy

**TurboSMS** — optional SMS delivery of the receipt link. If enabled, the customer phone number and receipt text are sent to `https://api.turbosms.ua`. Privacy policy and terms: https://turbosms.ua/privacy.html

== Changelog ==

= 0.5.3 =
* Escaped late on every output: the receipt link and additional content in the plain-text email template, and all generated form controls and badges on the settings screen (wp_kses with an explicit allowlist)
* CSV export writes to the output stream with documented phpcs exceptions instead of tripping the filesystem sniff
* readme translated to English

= 0.5.2 =
* Unique prefix `catcodeprro_` for all options, hooks, meta keys and tables (was `mpc_`)
* Admin styles and scripts moved to assets/ and enqueued with wp_enqueue_* (no inline <style>/<script>)
* Added the "External services" section (Vchasno.Kasa, Checkbox, KeyCRM, TurboSMS)
* Removed the non-functional Cashalot/SmartPos adapters
* Renamed to "Catcode PRRO Connector" (previously Multi PRRO Connector), new text domain `catcode-prro-connector`
* Translations come from translate.wordpress.org — `load_plugin_textdomain()` is no longer needed (WP 4.6+)
* The WordPress.org build no longer ships compiled .po/.mo files (only the .pot)

= 0.5.0 =
* Built-in KeyCRM source: fiscalise paid Rozetka/Prom/Instagram orders through the KeyCRM Open API
* Every KeyCRM order is fiscalised exactly once; run log; 60 requests/minute limit with 429 handling

= 0.4.0 =
* Rebuilt settings screen: one guided flow instead of scattered tabs
* Large status block (working / needs attention), numbered steps, plain language
* Technical options moved into a collapsed "Advanced" section
* The Vchasno register turns on automatically once the key is entered
* One-click "Save and test connection" button
* Fix: correct Checkbox API base URL (api.checkbox.in.ua)

= 0.3.1 =
* Settings split into tabs: General, Receipt, Shift, Notifications, Vchasno.Kasa, Checkbox
* Secret protection: API keys and passwords are never rendered into HTML, an empty field no longer wipes a stored value
* Fix: shift-close logging failed on the NOT NULL constraint on opened_at

= 0.3.0 =
* Automatic shift management: scheduled open/close through /api/v3/fiscal/execute
* Twice-daily cron (configurable, by default 00:01 open and 23:59 close with a report)
* Auto-open on sale: if the shift is closed when an order arrives, the plugin opens it and retries the receipt
* Manual open/close buttons on the Shifts screen
* Real open_shift/close_shift in the Vchasno adapter

= 0.2.1 =
* Cleanup: Cashalot/SmartPos removed from the UI (non-functional adapters)
* Fix: AbstractAdapter — wp_remote_request failed on an stdClass body in WP 6.x

= 0.2.0 =
* Real Vchasno endpoints (POST /api/v1/orders with rro_fn/tag/goods/total_sum/payment_type)
* Fixed a critical coupon bug: sum(items) == total
* Fixed retry of failed receipts (the logger now upserts)
* Fixed duplicate receipts on an empty fiscal_id
* UKTZED product code plus a shop-wide default
* Phone normalisation to +380…
* Configurable cash payment methods
* "Issue receipt" button on the order screen
* Options to skip zero-price items and to include shipping
* CSV export of receipts and bulk PDF opening
* WooCommerce email template for the customer receipt
* `catcodeprro_after_fiscalize` hook for third-party integrations
* TurboSMS starter
* Settings cache with autoload=yes
* Vchasno refunds leave a neutral note instead of a red error
* Ukrainian UI with tooltips

= 0.1.0 =
* First release with the base auto-fiscalisation flow.
