=== Factella – French E-Invoicing for WooCommerce ===
Contributors: roborock61
Tags: factur-x, e-invoicing, france, invoice, woocommerce
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Prepare your WooCommerce store for French e-invoicing: Factur-X invoices and credit notes, business identifiers at checkout, gap-free numbering.

== Description ==

From 1 September 2026 every French VAT-registered business must be able to receive electronic invoices, and from 1 September 2027 small and medium businesses must issue B2B invoices electronically and report B2C sales to the tax administration.

Factella prepares small WooCommerce shops for that mandate.

* Adds optional SIRET and VAT number fields at checkout (block and classic checkout).
* Validates SIREN, SIRET and French VAT numbers.
* Numbers invoices and credit notes in one gap-free chronological sequence (PPF-compatible, max 20 characters).
* Creates an invoice when an order is paid or completed, and a credit note for every refund.
* Generates a **Factur-X** file for each invoice and credit note: a PDF/A-3 with embedded EN 16931 CII XML, including the French mandatory mentions and the 2026 national rules (BR-FR). Validated against the official FNFE-MPE validator.
* Uses the exact WooCommerce VAT rate per line, and handles standard VAT, mixed rates, reduced rates, shipping and fees.
* Covers the French exemption cases: *franchise en base* (VATEX-FR-FRANCHISE), intra-EU reverse charge (category K / VATEX-EU-IC) and export outside the EU (category G / VATEX-EU-G).
* Branded, French, human-readable PDF with your logo and accent colour.
* Attaches the PDF to the customer's order emails and offers a download from the customer account.
* Bulk generation and ZIP export for past orders, plus a `wp factella generate` WP-CLI command.
* Exposes the invoice data (read-only) on the WooCommerce orders REST API.
* Readiness check and a period report (B2B, B2C by VAT rate, refunds) with CSV export.
* Optional transmission of B2B / B2BInt invoices and credit notes to the **SUPER PDP** platform with your own SUPER PDP account (manual button or automatic, with status tracking). B2C sales are never transmitted — they belong to e-reporting.
* Looks up the company name from a SIRET at checkout against the French public business register.

Factella is an independent project and is not affiliated with or endorsed by WooCommerce, Automattic or the French tax administration (DGFiP).

== Installation ==

1. Upload the plugin to `/wp-content/plugins/` and activate it.
2. Go to WooCommerce > Settings > Factella and fill in your legal name, SIREN, VAT number, VAT regime and bank details.
3. Place a test order and set it to the configured status; the invoice and its Factur-X PDF are created automatically.

== Frequently Asked Questions ==

= Does this send my invoices to the tax platform? =

No. Factella generates compliant Factur-X files and lets you download and email them. Transmission to an approved platform is not included.

= Which invoice format is produced? =

Factur-X (EN 16931 / "EN16931 Comfort" profile): a PDF/A-3 with the structured CII XML embedded, which is the format required by the French reform.

== External services ==

These connections are optional. No data is transmitted until you enter your own credentials and either click a send button or enable automatic sending.

**SUPER PDP (approved e-invoicing platform).** When you connect your own SUPER PDP account and send an invoice (manually or automatically), Factella authenticates with SUPER PDP using OAuth2 (client_credentials) and transmits the document.
* Data transmitted: your SUPER PDP client ID and client secret (for authentication), and, for each sent document, the Factur-X PDF and its invoice data (seller and buyer legal name, address, SIREN/SIRET, VAT number, line items and amounts), the invoice number (as the external reference), and status/payment events.
* When: only when you click "Test connection", "Send to SUPER PDP", or have enabled automatic sending; and periodically to read back the lifecycle status of documents already sent.
* Endpoints: https://api.superpdp.tech/oauth2/token and https://api.superpdp.tech/v1.beta/
* Terms of use: https://www.superpdp.tech/ — Documentation: https://www.superpdp.tech/documentation

**Annuaire des Entreprises (recherche-entreprises.api.gouv.fr).** At checkout, when a SIRET is entered, Factella asks this free public French government service for the matching company's legal name to help fill the company field.
* Data transmitted: the SIREN (the first 9 digits of the SIRET). No customer personal data is sent.
* When: only while a SIRET is being entered on the checkout; results are cached for one day and the request is rate-limited.
* Endpoint: https://recherche-entreprises.api.gouv.fr/search
* Terms: https://api.gouv.fr/les-api/api-recherche-entreprises — the data is the open public business register (data.gouv.fr).

== Privacy ==

Factella does not send any data to its developer or to any Factella-operated server. Invoice transmission goes from your site directly to **your own** SUPER PDP account; the buyer's invoice data (name, address, SIREN, amounts) is shared only with SUPER PDP, under your account and your agreement with them. The company-name lookup sends only a SIREN (public identifier) to a French government open-data service. All platform credentials are stored encrypted in your own database.

== Screenshots ==

1. Seller settings and the readiness check under WooCommerce > Settings > Factella, including the SUPER PDP connection.
2. The invoice box on the order screen: Factur-X download and the SUPER PDP transmission status (sent, delivered, accepted).
3. A generated Factur-X invoice (PDF/A-3 with embedded EN 16931 XML).

== Changelog ==

= 0.3.0 =
* New: transmit B2B / B2BInt invoices and credit notes to the SUPER PDP platform with your own account (OAuth2 client_credentials). Manual "Send" button and opt-in automatic sending, queued with Action Scheduler and retried with backoff on transient failures.
* New: transmission status on the order screen and list (sent / accepted / rejected), polled periodically; clear French error messages (invalid credentials, company not verified, invalid invoice, rate limit, platform unavailable).
* New: SUPER PDP connection settings (sandbox / production, encrypted secret, "Test connection"), plus connection/verification/sandbox lines in the readiness check.
* New: company-name auto-fill from a SIRET at checkout via the French public business register (cached, rate-limited, non-blocking).
* B2C sales are never transmitted (they belong to e-reporting) and are shown as such on the order.

= 0.2.0 =
* Correctness: per-line VAT rate read from WooCommerce (not derived); fees added as invoice/credit-note lines; total reconciled to the order total via the rounding amount (BT-114); unit price with 4 decimals.
* VAT categories: intra-EU reverse charge (K / VATEX-EU-IC) and export outside the EU (G / VATEX-EU-G), in addition to standard, zero and franchise en base.
* Pre-generation EN 16931 validation blocks an inconsistent invoice.
* New: readiness check on the settings tab, and a period report (B2B / B2C by VAT rate / refunds) with CSV export.
* Logo can be picked from the media library; WP-CLI command renamed to `wp factella generate`.

= 0.1.0 =
* Business identifiers at checkout, gap-free numbering, invoice and credit note records.
* Factur-X (PDF/A-3 + EN 16931 CII) generation, validated against the FNFE-MPE validator.
* Branded French PDF, email attachment, customer download, bulk generation, ZIP export and REST API field.
