=== Factella – Factur-X E-Invoicing for WooCommerce ===
Contributors: roborock61
Tags: facture électronique, factur-x, woocommerce, e-reporting, facturation électronique
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 0.5.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Factur-X e-invoicing for WooCommerce: compliant invoices & credit notes, SIREN/VAT at checkout, gap-free numbering. Ready for the 2026–2027 reform.

== Description ==

Factella prepares small WooCommerce shops in France for the e-invoicing reform — for free.

**The mandate, in short**

From 1 September 2026, every French VAT-registered business must be able to *receive* electronic invoices. From 1 September 2027, small and medium businesses and micro-enterprises must in turn *issue* their B2B invoices electronically and *report* their B2C sales to the tax administration (e-reporting). Dates are set by the reform and may change — always check your own situation with the tax authorities or your accountant.

**Who is it for?**

Small French WooCommerce shops — online merchants, freelancers and VAT-registered businesses — that sell to other businesses (B2B) and/or to private individuals (B2C) and want compliant invoices without changing their workflow or hiring a developer.

**What Factella does (free)**

* 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 across all 9 Factur-X invoice/credit-note scenarios.
* 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.

**Going further — Factella Pro**

The free plugin already generates compliant Factur-X files and can transmit them through *your own* account on an approved platform (Plateforme Agréée, PA). **Factella Pro removes even that step: it connects you to an approved platform in one click, with no separate platform account to create** — plus automatic B2C e-reporting and a supplier-invoice inbox. See https://getfactella.com. The free plugin remains fully functional on its own.

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? =

Not on its own. Factella generates compliant Factur-X files and lets you download and email them. It can also transmit them to an approved platform using your own SUPER PDP account (optional). A fully managed, one-click connection is available in Factella Pro.

= How does Factur-X work with WooCommerce? =

When an order is paid or completed, Factella creates the invoice automatically and generates a Factur-X file: a human-readable PDF (PDF/A-3) with the structured EN 16931 XML embedded inside it. The PDF is attached to the order emails and available from the customer account — nothing to design or fill in by hand.

= 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.

= What is an "approved platform" (Plateforme Agréée, PA)? =

Under the French reform, electronic invoices between businesses must transit through an approved platform (Plateforme Agréée, PA — formerly called "PDP"). Factella can send to SUPER PDP, an approved platform, using your own account. Factella Pro offers a one-click connection without configuring an account.

= What is B2C e-reporting? =

Sales to private individuals are not "e-invoiced", but their data must be reported periodically to the tax administration (e-reporting). The free plugin gives you a B2C report by VAT rate that you can export (CSV); Factella Pro aggregates and files it automatically.

= What does Factella Pro add? =

A one-click connection to an approved platform (no credentials to set up), automatic B2C e-reporting, a supplier-invoice inbox with approve/reject, and lifecycle status sync. The free plugin stays fully functional without it.

= Is Factella compatible with PDF Invoices & Packing Slips for WooCommerce? =

Yes. When that plugin is active, Factella shows a Compatibility section where you choose a single invoice-number source, so your customers never receive two invoice numbers for the same order. A good setup is to keep PDF Invoices & Packing Slips for packing slips and let Factella produce the compliant Factur-X invoice.

= Does Factella support Chorus Pro (public sector, B2G)? =

Not yet. Factella covers B2B electronic invoicing and B2C e-reporting through an approved platform (such as SUPER PDP). Chorus Pro, used for invoices to public bodies (B2G), is on the roadmap.

= Is Factella itself a Plateforme Agréée (PA)? =

No. Factella is a WooCommerce plugin that prepares your Factur-X invoices and transmits them; it is not itself an approved platform. It connects to a Plateforme Agréée (PA, formerly "PDP") such as SUPER PDP — the operator accredited and controlled by the State — which carries out the actual transmission and reporting.

== 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 (an approved e-invoicing platform, Plateforme Agréée).** 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).
4. The three-step setup wizard shown once after activation.
5. The period report (B2B and B2C by VAT rate) used for e-reporting, with CSV export.

== Changelog ==

= 0.5.1 =
* Improved WordPress.org listing (title, tags, FAQ) and added setup-wizard and e-reporting-report screenshots. No functional change.

= 0.5.0 =
* New: a first-run setup wizard — three short, skippable steps (seller identity, VAT regime & numbering, bank & logo) that lead to the readiness check. Shown once.
* New: an optional, permanently-dismissible review request on the Factella settings tab after a few invoices (never a dashboard notice; no incentive).
* New: compatibility with "PDF Invoices & Packing Slips for WooCommerce" — when it is active, a Compatibility section lets you pick a single invoice-number source so customers never get two invoice numbers.

= 0.4.0 =
* New: a dismissible one-line note on the Factella settings tab pointing to Factella Pro (one-click SUPER PDP connection, automatic B2C e-reporting, purchase inbox). Shown only on our own tab, never as a dashboard notice.

= 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.
