=== Matheel – ZATCA e-invoicing for WooCommerce ===
Contributors: matheel
Tags: zatca, e-invoicing, fatoora, saudi, vat
Requires at least: 6.2
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 0.2.0
License: GPLv2 or later

Every paid order becomes a ZATCA Phase 2 invoice with a bilingual PDF/A-3 and QR, emailed to the customer. Every refund becomes a credit note.

== Description ==
فاتورة زاتكا (المرحلة الثانية) تلقائية لكل طلب مدفوع في ووكومرس: تنرسل للهيئة، ويوصل العميل PDF عربي وإنجليزي فيه رمز QR. وكل استرداد (كامل أو جزئي) يطلع له إشعار دائن.

* One step: paste your Matheel key, press "Connect your device", finish the ZATCA OTP on the page that opens. The device token comes back to your shop by itself.
* Paid orders are filed in the background (Action Scheduler), one at a time under a database lock, so checkout never waits and an order never gets two invoices.
* Failed filings retry by themselves (every 5 minutes, same invoice uuid, so ZATCA never sees it twice). Only a real rejection stops: the order is marked "error" with ZATCA's reason in the order notes. A missing key or plan shows an admin notice and keeps retrying.
* Refunds (full or partial) are filed as credit notes for the refunded lines, after the original invoice is accepted.
* VAT per line: with WooCommerce taxes on, taxed lines are standard-rated (S) and untaxed lines are zero-rated (Z, with the exemption reason you pick), outside scope (O), or left off, per the settings page. With taxes off, prices are treated as VAT-inclusive: the invoice total equals what the customer paid.
* Negative fees (discounts) become one document-level discount when every line is standard-rated; otherwise the order is marked "error" with a note.
* The PDF and the legal XML are saved in your uploads, attached to the "Completed order" email, and linked on the customer's order page.
* Nothing is stored at Matheel: the invoice chain lives in your own database.

Docs: https://matheel.app/docs#nocode · Try the sandbox free, no key needed.

== Installation ==
1. Plugins → Add New → Upload → matheel-woocommerce.zip → Activate.
2. WooCommerce → Matheel ZATCA: key (empty for the sandbox), environment, lines with no tax, "Connect your device".

== Changelog ==
= 0.2.0 =
* One invoice per order, even when payment hooks fire twice: the order is re-read under the chain lock and everything is stored before the lock is released.
* Retries: network errors, timeouts, ZATCA outages, rate limits and busy chains are retried; a stale device token is replaced by the latest one; an earlier unanswered invoice is resent first; a document ZATCA already accepted ("already_filed") is marked filed, never sent again.
* A 200 without a device token (a firewall or HTML page) no longer wipes the token.
* "File with ZATCA" is offered only on orders not filed yet.
* Refunds become credit notes.
* Per-line VAT categories (S/Z/O) and a zero-tax setting; negative fees as a document discount.
* The activation callback takes the chain lock before storing the token.

= 0.1.0 =
* First release.
