=== Invoice-api.xhub for WooCommerce ===
Contributors: devxhubio
Tags: woocommerce, invoice, e-invoice, xrechnung, zugferd
Requires at least: 6.4
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free plugin connecting WooCommerce to invoice-api.xhub.io for compliant e-invoices (XRechnung, ZUGFeRD, Factur-X, UBL/Peppol, PDF) per EU mandates.

== Description ==

This is a **free** plugin that connects WooCommerce to the [invoice-api.xhub.io](https://invoice-api.xhub.io) e-invoicing service. The plugin itself is fully open source under GPLv2-or-later. To generate invoices you need an active subscription with invoice-api.xhub.io — service plans start at modest monthly tiers, see [console.invoice-api.xhub.io](https://console.invoice-api.xhub.io) for current pricing.

This is the same model used by Stripe, PayPal, Mollie, Mailchimp, and Zapier WordPress plugins: free open-source connector + paid third-party service.

It targets the EU e-invoicing mandates rolling out between 2025 and 2028 — Germany (XRechnung/ZUGFeRD, mandatory B2B receive 2025, send 2027/28), France (Factur-X, mandatory 2026/27), Italy (FatturaPA, mandatory since 2019), and 25 more countries.

= Supported formats =

* PDF (all 28 countries)
* UBL / Peppol BIS 3.0 (most EU countries)
* XRechnung (DE)
* ZUGFeRD (DE, CH)
* Factur-X (FR)
* FatturaPA (IT)
* Facturae (ES)
* ebInterface (AT)
* ISDOC (CZ)
* NAV (HU)
* myDATA (GR)
* Peppol UBL (PL, PT, RO)
* QR-Bill (CH)

Not every format is available for every country — the format dropdown shows the valid country combinations, and PDF works everywhere as the universal fallback.

= How it works =

1. You install the plugin and add your invoice-api.xhub.io API key.
2. You configure the default country, format, and seller details.
3. When an order reaches the configured trigger (default: completed), the plugin POSTs the order to the API and stores the returned invoice file on the order.
4. The customer-facing email gets the invoice file attached automatically (configurable).
5. The order edit screen has a meta box to manually generate, re-generate, and download the invoice.

= Video walkthroughs =

Setup and feature videos are on the Invoice-api.xhub YouTube channel: [youtube.com/@invoice-api-xhub-io](https://www.youtube.com/@invoice-api-xhub-io)

= What this plugin does NOT do =

* It does not host an OCR or template engine — generation is delegated to the API.
* It does not bypass WooCommerce taxes — tax rates are derived from line totals as WooCommerce computes them.
* It does not submit invoices to government portals (Peppol, FatturaPA SDI, KSeF). The XML/PDF is produced on the server and stored on the order; submission is your responsibility.
* It does not work without an API key — sign up at https://invoice-api.xhub.io to obtain one.

= External services =

This plugin relies on the third-party service **invoice-api.xhub.io** to generate the invoice files (XRechnung XML, ZUGFeRD PDF, Factur-X PDF, etc.). It is required for the plugin to function — invoice generation cannot happen locally because the service produces standards-compliant e-invoices using server-side libraries that are not bundled with this plugin.

**Endpoint:** `https://service.invoice-api.xhub.io/api/v1/invoice/{country}/{format}/generate`

**What is sent:** for every order processed (auto on a status transition you configure, or manually via the meta box):

* Seller information from your plugin settings: company name, VAT ID, street, postal code, city, country, email, IBAN, BIC (if configured)
* Buyer information from the order's billing address: name (or company), street, city, postal code, country code, email
* Order line items: description, quantity, unit price, tax rate, tax category, net/tax/gross amounts
* Order metadata: invoice number, dates, currency, payment terms, country-specific fields (e.g. Leitweg-ID for DE)

**What is NOT sent:** WordPress user accounts, password hashes, payment-gateway credentials, server logs, plugin/theme lists.

**When data is sent:** only after you have configured an API key (no calls happen on activation or before configuration), and only at one of: (a) the configured order status transition, (b) when you click "Generate" / "Re-generate invoice" in the order meta box.

**Service provider:** xhub.io — see the Privacy / GDPR section below for the full data-flow description.

By configuring your API key and saving the plugin settings, you consent to this data being transmitted to invoice-api.xhub.io for the sole purpose of generating compliant e-invoices.

= Privacy / GDPR =

The plugin stores the generated invoice file (base64-encoded) and metadata on the WooCommerce order itself, using order custom fields prefixed with `_invoice_api_xhub_`. This includes the buyer's billing details that are part of the invoice payload and will appear in the generated XML/PDF.

When a WordPress administrator processes a personal-data export request (Tools → Export Personal Data), the plugin contributes the invoice number, generation timestamp, format, and filename for each order belonging to the requested email address.

When a personal-data erasure request is processed, the plugin deletes the stored invoice payload and all associated metadata for orders belonging to the requested email address.

== Installation ==

1. Upload the plugin folder `invoice-api-xhub-for-woocommerce` to `/wp-content/plugins/`, or install through the Plugins screen.
2. Activate the plugin.
3. Open WooCommerce -> Settings -> Integrations -> Invoice-api.xhub.
4. Paste your API key, set country/format and seller details, save.
5. Place a test order and move it to the trigger status (Completed, by default).

== Frequently Asked Questions ==

= Does it work without WooCommerce? =

No. WooCommerce 8.0 or later is required. The plugin fails closed and shows an admin notice when WooCommerce is missing.

= Does it support High-Performance Order Storage (HPOS)? =

Yes. The plugin declares `custom_order_tables` compatibility. Order data is read through the WC_Order API, not directly from `wp_posts`.

= Where is the invoice file stored? =

In `/wp-content/uploads/invoice-api-xhub/<order-id>/<filename>`. The plugin writes a `.htaccess` file with `Deny from all` to block direct URL access (Apache). On Nginx, add `location ~ /uploads/invoice-api-xhub/ { deny all; }` to your server config — invoices contain buyer addresses and must not be web-accessible. Order meta stores only the relative path. Older installs of the plugin (≤ v0.x) stored the base64 payload directly on the order; the read path supports both for backward compatibility.

= Can I re-generate an invoice after editing the order? =

Yes. Open the order, find the Invoice-api.xhub meta box on the right, click "Re-generate invoice".

= Does it submit to the German XRechnung B2G portal? =

No. The plugin produces the XRechnung XML and stores it on the order. You upload it to the federal/state platform yourself, or pass it to your accounting software which does.

= Where does the buyer reference / Leitweg-ID come from? =

Order meta `_invoice_api_xhub_leitweg_id` or `_invoice_api_xhub_buyer_reference` if set, then the global Leitweg-ID from settings, finally the WooCommerce order number as buyer reference.

= Why does the plugin call base64_decode? =

The invoice-api.xhub.io API returns the generated XML or PDF file as a base64-encoded string in the JSON response (this is the standard pattern for delivering binary data over JSON). The plugin decodes that string with `base64_decode()` so it can be served to the merchant as a download or attached to the customer email. The function is not used to evaluate or execute any data — only to decode HTTP-response payload. The decoded content is treated as opaque file bytes and never passed to `eval`, `assert`, `create_function`, or similar.

= Is the plugin §14 UStG (DE) compliant for invoice numbering? =

Out of the box, the default format `INV-{order_number}` reuses the WooCommerce order number, which is **not** guaranteed to be gap-free across the entire system (deleted orders, other plugins reserving IDs). For German tax compliance use a format with the `{seq}` token, e.g. `2026-{seq:0000}`. The plugin maintains a separate sequential counter that is uniquely incremented for every generated invoice, with optional yearly or monthly reset.

= Can I use a custom invoice template? =

Yes. By default the plugin uses the standard template provided by invoice-api.xhub.io. To use your own:

1. Log in to https://console.invoice-api.xhub.io/pdf/templates
2. Create a new template (or copy one of the starter templates) — adjust layout, logo, colors, header/footer blocks
3. Save and copy the Template-ID (UUID format, e.g. `550e8400-e29b-41d4-a716-446655440000`)
4. In WordPress: WooCommerce → Settings → Integration → Invoice-api.xhub → "Default Template-ID" — paste it, save

From now on every generated invoice uses your template. Templates are format-specific — a template designed for XRechnung will not work for ZUGFeRD or PDF.

To use a different template for a specific order (e.g. B2C vs. B2B layouts), set the order's custom field `_invoice_api_xhub_template_id` before the generate fires. Per-order override beats the global default.

== Screenshots ==

1. Fully automatic workflow — every order becomes a compliant e-invoice without manual steps.
2. 13 e-invoice formats across 28 European countries: PDF, UBL/Peppol BIS 3.0, XRechnung 3.0 (DE), ZUGFeRD 2.3 (DE/CH), Factur-X (FR), FatturaPA (IT), and more.
3. Your customers receive their invoice automatically — auto-download link in every order confirmation email.
4. Built for the EU e-invoicing mandate timeline: B2B receive 2025, B2B send 2027 (large enterprises), full coverage 2028.
5. WooCommerce → Settings → Integration → Invoice-api.xhub — pick country, format, trigger, attach-to-email behaviour, and seller details in one panel.
6. Order detail with the Invoice-api.xhub meta box — generated filename, timestamp, plus Re-generate and Download buttons on every order.

== Changelog ==

= 1.1.0 =
* API v1.3.0: expanded from 14 to 28 supported countries; all country-specific e-invoice formats can now be generated (UBL/Peppol BIS 3.0, Factur-X, FatturaPA, Facturae, ebInterface, ISDOC, NAV, myDATA, Peppol-UBL, QR-Bill).
* Removed the "Coming Q3 2026" roadmap copy — those formats are live.
* Added link to the Invoice-api.xhub YouTube channel.
* Tested up to WordPress 7.0 and WooCommerce 10.8.

= 1.0.2 =
* Removed wp.org directory assets (banner, icon) from the plugin ZIP per the directory-assets guideline; these files now live alongside the plugin and will be uploaded via SVN /assets/ after approval.

= 1.0.1 =
* Renamed internal constants to brand-anchored prefix (`INVOICEAPIXHUB_*`) to comply with WordPress.org prefix guidelines (avoid `WC_` namespace collisions).
* Removed broken external Terms / Privacy URLs from readme — full data-flow description remains in the Privacy / GDPR section.
* Corrected `Contributors` to the WordPress.org owner account.

= 1.0.0 =
* Initial release
* Generate, store, attach, and download invoices for 14 EU countries
* HPOS compatibility
* Per-order manual generate + re-generate
* Auto-attach to customer Completed/Processing/Invoice emails
