=== Raseedo Saudi E-Invoicing for WooCommerce ===
Contributors: hamzaahmadaslam
Tags: zatca, e-invoice, fatoora, saudi arabia, vat
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

ZATCA Phase 2 (Fatoora) e-invoicing for WooCommerce: onboard in one step, sign and report invoices and credit notes.

== Description ==

Saudi businesses above ZATCA's thresholds must integrate their invoicing with ZATCA's Fatoora platform (Phase 2). This plugin does that for a WooCommerce store:

* **Onboarding in one step.** Paste the OTP from your Fatoora portal account. The plugin creates the key and certificate request, gets the compliance certificate, passes ZATCA's six compliance checks and gets the production certificate.
* **An e-invoice for every paid order.** A simplified tax invoice (UBL 2.1 XML) is created, signed with your certificate and given a QR code as soon as an order is paid, then reported to ZATCA in the background.
* **Credit notes for refunds.** Refunds produce a credit note that references the original invoice and carries the refund reason.
* **The hash chain is kept in order.** Each document carries the invoice counter and the previous invoice's hash. Documents are created one at a time, so simultaneous checkouts never break the chain.
* **Retries.** Network problems and ZATCA outages are retried for hours, well inside ZATCA's 24-hour reporting window. Rejections are shown with ZATCA's reasons.
* **A bilingual invoice page.** Arabic and English, with the QR code, linked from the customer's order page and order emails. Customers open it with their order key.
* **Records kept.** Every signed XML and ZATCA response is stored. Uninstalling the plugin keeps them unless you explicitly ask for everything to be deleted.
* **Site Health.** Warns when e-invoicing is on but not onboarded, when the certificate is about to expire, or when documents wait too long.
* **Arabic admin.** The settings, onboarding and e-invoice screens come translated into Arabic and switch automatically when the site or user language is Arabic.

Start in ZATCA's sandbox (no Fatoora account needed), then switch to Simulation and Production with your real VAT number.

This plugin is built to ZATCA's published Phase 2 specifications. It is not affiliated with, endorsed or approved by ZATCA. You remain responsible for your tax compliance.

= External services =

This plugin connects to ZATCA's Fatoora API (https://gw-fatoora.zatca.gov.sa), the Saudi tax authority's e-invoicing platform, because Phase 2 e-invoicing requires it.

* When you onboard the store, it sends a certificate signing request (your VAT number, seller name, branch, National Address short code and business category) and the OTP you enter, plus six sample compliance documents built from your seller details.
* For each paid order and refund, it sends the signed invoice or credit note XML: seller details, line items, amounts and VAT, and, for standard (B2B) invoices, the buyer's details.

Nothing is sent until you onboard the store and turn on "Issue e-invoices". ZATCA's terms: https://zatca.gov.sa/en/Pages/TermsAndConditions.aspx and privacy policy: https://zatca.gov.sa/en/Pages/PrivacyPolicy.aspx

= Third-party code =

The invoice page draws the QR code with QR Code Generator for JavaScript by Kazuhiko Arase (MIT licence, https://github.com/kazuhikoarase/qrcode-generator), version 2.0.4, in assets/vendor/qrcode.js.

== Installation ==

1. Install and activate the plugin. WooCommerce must be active.
2. Go to WooCommerce > ZATCA E-Invoicing > Seller details and fill in your legal name, VAT number, commercial registration and National Address.
3. Keep the environment on Sandbox and open the Onboarding tab. The test OTP is filled in; click "Onboard this store".
4. Turn on "Issue e-invoices" and place a test order to see an invoice reported to the sandbox.
5. When ready, switch the environment to Simulation, onboard with an OTP from your Fatoora portal, test, then do the same for Production.

== Frequently Asked Questions ==

= Do I need a ZATCA-approved solution provider? =

No. ZATCA's Solution Providers Directory is an indicative list; ZATCA states that taxpayers are compliant when their solution meets the requirements, whether or not the provider is listed.

= Where do I get the OTP? =

Log in to the Fatoora portal (https://fatoora.zatca.gov.sa) with your ZATCA account and choose the option to onboard a new solution unit. The OTP is valid for one hour. The sandbox needs no OTP from you.

= What happens if ZATCA rejects a document? =

It stays in the list as rejected, with ZATCA's reasons, and the order gets a note. ZATCA counts it in the hash chain, so it is never deleted. Fix the cause (usually seller details) and issue a corrected document.

= Does it handle B2B (standard) invoices? =

The signing, clearance and reporting code handles both. Free installs issue simplified (B2C) invoices. Developers can switch an order to a standard invoice with the `saudi_einv_audience` filter and add buyer details with `saudi_einv_document`.

= My site's security keys changed and onboarding is lost. =

Certificates are encrypted with the site's AUTH_KEY and SECURE_AUTH_KEY. If those change, onboard again with a new OTP. Issued invoices are not affected.

== Screenshots ==

1. Seller details: legal name (Arabic recommended), VAT number, National Address and the environment.
2. Onboarding: paste the OTP from the Fatoora portal; the plugin passes ZATCA's compliance checks and stores the certificate.
3. The e-invoice list with ZATCA's status for every invoice and credit note.
4. The bilingual invoice page with the ZATCA QR code, as the customer sees it.

== Changelog ==

= 1.0.1 =
* Fix: two payments of the same order at the same moment can no longer create two invoices (race-safe chain lock in its own table).
* Fix: amount-only refunds get a credit note at the order's VAT rate (split in proportion for mixed rates) instead of 0%.
* Fix: an invoice or credit note rejected by ZATCA can be issued again, corrected, with a new number.
* Fix: orders in currencies other than SAR are skipped with an order note and a Site Health warning instead of being invoiced as SAR.
* Fix: renewing the certificate keeps the current one in use until ZATCA issues the new production certificate; Site Health says when it has expired.
* Fix: "Retry now" only applies to e-invoices that could not be sent, so a waiting e-invoice is never sent twice.
* The invoice page follows the site language and direction (right to left in Arabic).

= 1.0.0 =
* First release.
