[Docs D-30] Troubleshooting — ZUGFeRD v1.0 → v2.3 migration · [Docs D-31] Upgrade from InvoicePlane v1.6.x to v1.8.0

[nielsdrost7]

Wiki section: Troubleshooting / Migration
Tier: 4 — Troubleshooting
Publish when: InvoicePlane v1.8.0 is released

---

D-30: ZUGFeRD v1.0 → v2.3 migration

Background

ZUGFeRD v1.0 (provided by Zugferdv10.php / Zugferdv10Xml.php) was included in InvoicePlane from v1.4.7 through v1.6.2. Its XML structure is substantially different from ZUGFeRD v2.x — they are not backward compatible and modern validators reject v1.0 files.

When to migrate

Migrate immediately for all new invoices. Historical invoices already issued as ZUGFeRD v1.0 do not need to be re-generated — what was delivered to the client at the time was valid under the standard in force.

Migration steps

1. Assign a v2.3 template to the client

   • Open the client record → E-invoicing tab
   • Change the template from ZUGFeRD v1.0 to ZUGFeRD v2.3 - comfort (or your preferred profile)

2. Fill in any new required fields

   • user_iban — required for payment means block
   • user_vat_id — required for seller tax registration

3. Remove the v1.0 config (optional)

   • The Zugferdv10.php config is automatically excluded on setup if the include_zugferd option is disabled
   • If you want to keep it visible for reference only, leave it — it will not affect v2.3 generation

4. Validate the first v2.3 invoice against the Invoice portal validator before sending

Key structural differences

Aspect	ZUGFeRD v1.0	ZUGFeRD v2.3
XML root element	rsm:CrossIndustryDocument	rsm:CrossIndustryInvoice
Profile namespace	urn:ferd:...	urn:cen.eu:en16931:2017 (comfort)
EN 16931 compliance	No	Yes
Modern validator support	❌ Rejected	✅ Accepted
Generator	Zugferdv10Xml	Facturxv10Xml

---

D-31: Upgrade from InvoicePlane v1.6.x to v1.8.0

What changes in the e-invoices module

New database fields (provided by the core v1.8.0 migration)

Field	Table	Description
client_peppol_id	ip_clients	Peppol Participant ID
client_company_number	ip_clients	Company registration number
client_einvoice_sdi_code (key)	ip_client_meta	FatturaPA SdI routing code
client_einvoice_pec_email (key)	ip_client_meta	FatturaPA PEC email
invoice_routing_code_1/2/3 (keys)	ip_invoice_meta	Procurement routing codes

No migration SQL is needed in this module — all schema changes are handled by the core InvoicePlane v1.8.0 migration script.

Updated generators (v1.8.0)

Change	What it affects
Payment means guard added	Factur-X / ZUGFeRD — prevents BR-50/BR-61 errors when IBAN is absent
French PDP compliance	Factur-X — GuidelineID, BR-FR-02, SIREN fields, BT-34/BT-49 (see issue #11)
client_peppol_id read	All Peppol UBL configs
client_company_number read	All generators where applicable
Routing codes from ip_invoice_meta	XRechnung, FatturaPA B2G, Facturae B2G

Upgrade steps

1. Back up your database and files

2. Run the InvoicePlane v1.8.0 core migration — this adds the new columns and any required ip_client_meta/ip_invoice_meta keys

3. Copy updated module files into application/helpers/XMLconfigs/ and application/libraries/XMLtemplates/

4. Re-install vendor libraries if using Italy or Spain:

   cd application/libraries/XMLtemplates/fatturapa/ && composer install
   cd application/libraries/XMLtemplates/Facturae/ && composer install

5. Fill in new client fields for any existing e-invoicing clients:

   • Peppol Participant ID (if applicable)
   • Company registration number (if applicable)

6. Validate one invoice per format to confirm the updated generators behave correctly

Existing invoices

Historical invoices stored in the database are unaffected. Re-exporting them through updated generators will use the new generator code. If any existing invoice would produce different XML (e.g. because it now includes a new field), consider whether re-export is needed for your records.

---

Migrated from InvoicePlane/InvoicePlane-e-invoices#54.