=== BokaPOS for WooCommerce ===
Contributors: bokagroup
Tags: woocommerce, fiscalization, fiskalizacija, serbia, esir
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Fiscalizes WooCommerce orders through BokaPOS, the cloud ESIR for distance commerce in Serbia.

== Description ==

BokaPOS for WooCommerce connects your shop to BokaPOS (https://bokapos.rs), a cloud ESIR that issues fiscal receipts through the Tax Administration's virtual fiscal processor (V-PFR) for distance commerce in Serbia. BokaPOS 1.0.0 is approved by the Tax Administration as ESIR IB 1656 (decision 000-092-00-00171/2026-0000 of 2 September 2026).

Install, enter the client id and secret BokaPOS issued, and map your tax classes and payment methods once. From then on you fiscalize an order with one click from the order screen, or switch on automatic fiscalization and let every order at the status you choose get its receipt: the PFR number, the Tax Administration verification link, the QR code and the PDF, stored on the order and delivered to the customer.

**What it does**

* Fiscalizes orders manually from the order screen and the orders list, or automatically at the status you choose (Completed recommended).
* Refunds through the BokaPOS refund workflow, including the signed copy for cash refunds.
* Advance chains (advance receipt at payment, advance refund and final receipt at delivery) for gateways you mark as prepaid.
* Copies, proforma and training documents from the order screen.
* Receipt delivery: WooCommerce e-mails with the PDF, BokaPOS platform e-mails, the order-received page and My Account.
* Company purchases: PIB field at checkout (classic and block checkout). The receipt carries the buyer identification; the registered company name BokaPOS resolves is shown on the order screen.
* Local fiscal journal, BokaPOS journal search, CSV export and the turnover report inside WordPress.
* Optional product catalogue sync.
* Serbian (Latin) and English.

**Safety rules the plugin follows**

* A receipt exists only when BokaPOS answers 201 with `fiscalized: true`. Nothing else counts.
* Every request carries an idempotency key stored before sending, so a network problem can never produce two receipts for one order.
* Unknown outcomes are never resent; the plugin checks the result with BokaPOS and tells you when a person needs to decide.
* Tax labels are read live from the V-PFR through BokaPOS; nothing is hard-coded.

**External service**

This plugin requires a BokaPOS account and sends order data to BokaPOS in order to issue fiscal receipts. The "External services" section below lists what is sent, when, and where the terms and the privacy policy are.

== External services ==

This plugin connects to BokaPOS, the cloud ESIR operated by BOKA GROUP DOO (Belgrade, Serbia), to issue the merchant's fiscal receipts through the Tax Administration's V-PFR. Without a BokaPOS account the plugin does nothing. Nothing is sent until an administrator enters a BokaPOS credential, and nothing is ever sent about visitors who do not place an order.

What is sent and when:

* Access tokens. When an administrator saves or tests a credential, and whenever a stored token has expired before an API call, the plugin sends the client id and secret to https://auth.bokapos.rs (OAuth 2.0 client credentials) and receives a short-lived bearer token.
* Fiscal documents. When a receipt, refund, advance receipt, copy, proforma or training document is issued, either from the order screen or by the automation the merchant switched on, the plugin sends to https://api.bokapos.rs the order lines (name, quantity, unit price, tax label, unit of measure, GTIN), the amounts and the payment type, the order number as a reference, the cashier name, the buyer identification the customer or the merchant supplied (for example a company PIB) and the shop's host name and plugin version as metadata.
* Receipt e-mails. When the merchant enables the BokaPOS e-mail channel, the customer's billing e-mail address is sent with a delivery request so BokaPOS can send the receipt.
* Reads. Connection checks, the taxpayer and premise list, tax labels, receipt PDFs and QR codes, journal searches, turnover reports and the daily health check read from https://api.bokapos.rs when a merchant opens the matching screen or the scheduled check runs.
* Catalogue. When the merchant enables catalogue sync, product SKU, name, gross unit price, unit of measure, tax label and GTIN are sent to https://api.bokapos.rs.

No data is sent to any other service and no analytics or advertising data is collected. BokaPOS terms of service: https://bokapos.rs/uslovi (English: https://bokapos.rs/en/uslovi). Privacy policy: https://bokapos.rs/privatnost (English: https://bokapos.rs/en/privatnost).

== Installation ==

1. Upload the plugin and activate it. WooCommerce 8.9 or newer and PHP 8.1 or newer are required.
2. Request BokaPOS access (office@bokagroup.rs). Use the sandbox credential for setup and test receipts; the production credential follows once the company certificate is active at BokaPOS.
3. Open WooCommerce, BokaPOS. Enter the credential, run "Test connection", choose the taxpayer and business premise, save.
4. In the Taxes tab map each tax class to a label read from the V-PFR. In the Payments tab confirm the payment types.
5. Place a test order. The order screen shows the receipt, the verification link and the PDF.
6. For production, the Owner uploads the company certificate in the BokaPOS portal; BokaPOS issues the production credential. Enter it and switch the environment. Nothing else changes.

== Frequently Asked Questions ==

= Does the plugin fiscalize orders created before it was installed? =

No. A receipt carries the time the V-PFR signs it, so old orders would receive today's time. Only orders created after activation are fiscalized.

= What happens when the V-PFR is down? =

Nothing is issued. The plugin repeats the same request with the same key a few times with growing delays; if the service stays down it flags the order and e-mails the administrator. A single "Retry" button repeats the same request.

= What does "Outcome being checked" mean? =

The request may have reached the V-PFR but the answer did not come back. The plugin never sends it again; it asks BokaPOS for the result periodically and finishes the order as soon as the result is known.

= Can a customer's refund be fiscalized without an identity number? =

No. The regulations require buyer identification on every refund. The refund panel asks for it (identity card number, PIB, passport and the other official kinds).

= Does the plugin support production fiscalization? =

Yes. BokaPOS is an approved ESIR (IB 1656), so production receipts are real fiscal receipts. Sandbox and production credentials, settings and token caches are isolated. Start with sandbox test receipts, then enter the production credential issued after BokaPOS onboarding and switch the active environment.

== Screenshots ==

1. Configure manual or automatic fiscalization, cashier details and advance-payment rules.
2. Map WooCommerce tax classes to the current labels fetched from the V-PFR.
3. View a confirmed fiscal receipt, verification link, representations and follow-up actions on the WooCommerce order.

== Changelog ==

= 1.0.0 =
* First release: fiscalization of sales, refunds, advance chains, copies, proforma and training documents, e-mail delivery, catalogue sync, journal, turnover report, Serbian and English.
* Rejects sandbox credentials in the production slot and production credentials in the sandbox slot before storage or API use.
* Fixes the stretched "Needs attention only" checkbox in the local journal filters.
* Shows the BokaPOS fields on the first WooCommerce refund, before any refund row exists.
* Rebuilds a never-sent fiscalization request after its tax mapping is corrected instead of offering an unusable same-request retry.
* Follows the BokaPOS contract as approved on 2 September 2026: every official payment type is accepted on every premise (the per-premise payment mode is gone), the optional buyer field is sent on the sale receipt only, and an advance refund is never e-mailed to the customer.
