E-Invoice: XRechnung 3.0, ZUGFeRD & Factur-X

Structured E-Invoicing for Dolibarr — 100 % Local

This module adds fully structured electronic invoicing to Dolibarr. It covers both German public-sector (B2G) and business-to-business (B2B) requirements in a single, self-contained package that runs entirely on your own server. No data leaves your system, no subscription to a third-party conversion service is required.

Export Formats

• XRechnung 3.0 (UBL 2.1) — Invoice and CreditNote documents, the format required for invoices to German federal authorities.
• ZUGFeRD / Factur-X (UN/CEFACT CII) — Structured XML embedded into the invoice PDF as a true PDF/A-3 hybrid file, using the bundled atgp/factur-x library. Recipients get a human-readable PDF and a machine-readable XML in one attachment.

Automatic Generation on Invoice Approval

When you validate (approve) an invoice in Dolibarr, the module automatically generates the XML and attaches it to the document. The trigger uses a soft-fail design: if generation fails, Dolibarr continues normally and logs the error rather than blocking the approval workflow.

Supplier Invoice Import

Upload a UBL 2.1 or CII XML file and the module creates a draft supplier invoice in Dolibarr. The supplier is matched by VAT number or company name; if no match is found, a new supplier record is created automatically. Line items are transferred without manual re-entry.

Built-in EN16931 Plausibility Check

Before generating or importing, the module runs a native PHP validation pass covering EN16931 mandatory-field rules (BR-* series) and arithmetic consistency rules (BR-CO-* series). The result is a clear list of errors and warnings shown directly in the Dolibarr interface.

Scope of validation: This is a core-rule plausibility checker implemented in native PHP. It is not the official KoSIT Schematron/Saxon XSLT 2.0 validation suite and does not carry official government certification. For submissions requiring KoSIT-certified pre-validation, run the XML through the official KoSIT Validator separately.

Leitweg-ID for Public-Sector Invoices (B2G)

A dedicated custom field (BT-10, Leitweg-ID) is created automatically in the customer record when the module is installed. Fill it in once per public-sector customer and it is included in every outgoing XRechnung automatically — no manual entry per invoice.

Configuration

• Profile selection (XRechnung 3.0 UBL / ZUGFeRD EN16931 / Factur-X EN16931)
• Auto-generation on invoice approval: on/off
• PDF/A-3 embedding: on/off
• EN16931 plausibility validation: on/off
• Optional Factur-X XSD schema check
• Test-generation button directly on the setup page
• XML import upload for supplier invoices
• Interface available in German and English

Technical Details

• License: GPLv3 — open source, no runtime licence key
• Dolibarr 18.0 – 24.0 (tested on 24.0.0)
• PHP 7.4 – 8.5
• No external API calls, no cloud dependency
• Bundled library: atgp/factur-x v3.3 for PDF/A-3 embedding

### Version 1.1.2
- **KoSIT XRechnung 3.0 & EN16931 Compliance Update**:
  - `BR-DE-21`: Updated specification identifier (`BT-24`) to the official current KoSIT URN `urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0`.
  - `PEPPOL-EN16931-R120`: Accurate item net price (`BT-146`) calculation when line discounts are present (`total_ht / qty`), ensuring exact mathematical consistency between item price and line total.
  - `BR-DE-TMP-32` & `BR-FX-EN-04`: Automatic output of delivery date (`BT-72` / BG-14) in both UBL (`cac:Delivery/cbc:ActualDeliveryDate`) and CII (`ram:ApplicableHeaderTradeDelivery/ram:ActualDeliverySupplyChainEvent`), derived from tax point date, delivery date, or invoice issue date.
  - `PEPPOL-EN16931-R008` & `FX-SCH-A-000372`: Complete removal of empty XML elements.
- **Fix for XML Embedding in PDF/A-3 Container**:
  - Automatic on-the-fly generation of the base invoice PDF if it does not yet exist on disk when the validation trigger fires.
  - Enhanced ZUGFeRD compatibility: In ZUGFeRD mode, both `factur-x.xml` and `zugferd-invoice.xml` are now embedded into the PDF/A-3 container, ensuring 100% compliance across both international Factur-X readers and German ZUGFeRD validators.
  - Implemented `afterPDFCreation` hook (context `pdfgeneration`): Regenerating invoice PDFs within Dolibarr automatically preserves and embeds the XML into the freshly generated document.
  - The test generation tool on the module setup page (`admin/setup.php`) now executes complete PDF/A-3 embedding with UI feedback.
  - Fully tested and validated end-to-end via Playwright (0 validation errors / 0 warnings).

### Version 1.1.1
- **New: Automatic Email Attachment**:
  - Generated e-invoices (XRechnung XML / ZUGFeRD XML) are now automatically pre-attached when opening the invoice "Send Email" composer (via FormMail hook).
  - New option: Automatically update/replace the main invoice PDF with the hybrid Factur-X PDF/A-3 file (`ERECHNUNG_REPLACE_PDF`), ensuring standard PDF downloads and emails always contain the valid e-invoice.
  - Both options can be toggled on/off in the module setup.
- **Dolibarr 24.0.0 & PHP 8.5 Compatibility**:
  - Fully tested and verified for Dolibarr 24.0.0 and PHP 8.5 (v8.5.8).
  - Resolved all PHP 8.5 deprecation warnings (explicit class property declarations, strict type checks, safe type conversions).
- **Stability & Bug Fixes**:
  - Hardened library and setup inclusion logic (`main.inc.php`, `admin.lib.php`, `files.lib.php`) to prevent variable scoping issues.
  - Fixed parameter alignment in supplier invoice import (`FactureFournisseur::addline`) for precise quantities, unit prices, and tax rates.
  - Improved fallback logic for company details, VAT IDs, and currency codes.

### Version 1.1.0
- **Dolibarr 24.0.0 & PHP 8.5 Compatibility**:
  - Full support and verification for Dolibarr 24.0.0.
  - Complete compatibility with PHP 8.5 (tested on PHP 8.5.8).
  - Resolved PHP deprecation notices: explicit property declarations (including `$license` in `modERechnung`), strict typing, and safe scalar type casts.
- **Supplier Invoice Import Improvements**:
  - Corrected parameter alignment in `FactureFournisseur::addline`: line item quantities, unit prices, and tax rates from UBL and CII XML are transferred with exact precision.
  - Enhanced supplier matching by VAT number, tax ID, or legal name.
- **Validation & Stability Enhancements**:
  - Robust null-checks in EN16931 plausibility validation (DOM root element and TaxSubtotal nodes).
  - Improved fallback handling for company master data, buyer metadata, and default currency codes.

### Version 1.0.0
- **Initial Release**:
  - Full generation of **XRechnung 3.0 (UBL 2.1)** for customer invoices and credit notes according to current B2G standards.
  - Full generation of **ZUGFeRD 2.5 / Factur-X 1.09 (UN/CEFACT CII)** as a hybrid PDF/A-3 container.
  - Automatic invoice generation upon approval (`BILL_VALIDATE`).
  - 100% on-premise execution — no cloud dependence, no external third-party services.
  - Import assistant for incoming supplier invoices from XRechnung and ZUGFeRD files with automatic matching.
  - Built-in EN16931 validation and configuration panel with test invoice generator.