ZUGFeRD valideren met Mustang: wat slaagt, wat faalt en waarom

Als u in 2026 e-invoices naar een Duitse B2B-klant stuurt, is het bestand ZUGFeRD-compliant of het wordt bij ontvangst geweigerd. In Frankrijk geldt hetzelfde met Factur-X. Het formaat is een PDF/A-3 wrapper met een EN 16931 CII XML attachment. Dat vanaf nul genereren is niet triviaal, en validatie vraagt om een reference engine.

In de praktijk is die engine Mustang (mustangproject.org): een open-source Java project dat embedded XML uit een PDF/A-3 haalt en valideert tegen EN 16931 Schematron. Mustang heeft de diepste ondersteuning voor ZUGFeRD en Factur-X onder open tools, en veel independent verifiers draaien het.

Dit artikel loopt door de failure modes die Mustang meldt en een snellere manier om het te gebruiken.

Wat Mustang echt controleert

Wanneer u een Factur-X- of ZUGFeRD-PDF aan Mustang geeft, gebeurt ongeveer dit:

1. Embedded file extraheren. PDF/A-3 bewaart attachments in de /EmbeddedFiles name tree. Mustang zoekt de canonieke bestandsnaam (factur-x.xml voor Factur-X, zugferd-invoice.xml voor ZUGFeRD 2.x) en leest de bytes.
2. AFRelationship controleren. Het attached file moet volgens de Factur-X / ZUGFeRD baseline AFRelationship="Alternative" declareren. Andere waarden (Source, Data, Supplement) falen.
3. XMP namespace en version controleren. Factur-X 1.0 gebruikt urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#. ZUGFeRD 2.x gebruikt urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#. Verkeerde namespace of version string faalt.
4. XML parsen als Cross-Industry Invoice (CII). Het moet well-formed XML zijn en beginnen met het juiste CII root element (rsm:CrossIndustryInvoice).
5. EN 16931 Schematron draaien. Dit is het grootste deel: ongeveer 200 business rules over field semantics, mandatory codes, totals math, VAT logic, party identifiers, enzovoort.

Pass = invoice is acceptabel voor elk EN 16931-conformant AP system in de EU. Fail = de AP automation van de klant wijst de invoice bij ontvangst af en het AR team krijgt een manual exception.

De vijf failure modes die we het meest zien

Deze komen vaak terug aan de Mustang-kant van validator wanneer teams hun eerste e-invoices testen.

1. Wrong AFRelationship

ERROR: Embedded file factur-x.xml uses AFRelationship="Source",
expected "Alternative".

De PDF spec staat meerdere relationship types toe voor attached files. Factur-X / ZUGFeRD vereisen Alternative: de attached XML is een alternative representation van de visible PDF content. Als uw PDF generator Data gebruikt (default in veel libraries), faalt Mustang direct. De zichtbare PDF rendert nog steeds, maar de structured payload is ongeldig voor het AP system.

2. Wrong / missing XMP namespace

ERROR: XMP metadata missing fx:DocumentType or fx:DocumentFileName under
namespace urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#.

Het XMP packet van de PDF moet declareren welk Factur-X profile dit is (MINIMUM, BASIC, EN 16931, EXTENDED) en welke filename gezocht moet worden. Bij handgeschreven PDF/A-3 wrappers wordt dit makkelijk gemist; gPdf /api/v1/e-invoice/render emit dit automatisch.

3. CII XML is well-formed, maar EN 16931 Schematron faalt

ERROR: BR-CO-25 — In an invoice (BR-01) the
  ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime is required when
  ram:DocumentTypeCode is 380.

Dit is het grootste deel van echte failures. De XML is syntactisch valid; de business rules falen. EN 16931 Schematron rules hebben stable IDs (BR-01, BR-CO-25, enz.) die u in de specificatie kunt opzoeken. Veelvoorkomend:

• BR-01: invoice moet een unique invoice number hebben.
• BR-04: invoice moet een issue date hebben.
• BR-05: invoice moet een invoice type code hebben.
• BR-CO-25: payment terms required wanneer document type “Commercial invoice” is.
• BR-Z-01: VAT category codes moeten een van S, Z, E, AE, K, G, O, L, M zijn.

Corrigeer source data, rebuild en re-validate.

4. De PDF/A wrapper valideert niet

INFO: CII XML extracted and validates against EN 16931.
ERROR: PDF/A-3b conformance check failed: missing Output Intent.

Hier slaagt Mustangs XML check, maar de onderliggende PDF/A-3 wrapper faalt. Vaak is het XML correct, maar werd een gewone PDF uitgegeven in plaats van PDF/A-3. Het embedded file is aanwezig, maar de archiefregels zijn niet gehaald. De validator op gpdf.com/validator/ vangt dit door veraPDF parallel te draaien: PDF/A-3 fail verschijnt in de veraPDF-kolom terwijl Mustang XML pass meldt.

5. Encoding / declaration mismatch

ERROR: XML declares <?xml version="1.0" encoding="UTF-8"?> but the
embedded byte stream is UTF-8 with BOM. Mustang strict mode rejects BOM.

Verrassend vaak wanneer een XML tool UTF-8 BOM emit en die bytes raw worden embedded. Oplossing: strip de BOM vóór embedding. De gPdf e-invoice endpoint normaliseert dit.

Mustang draaien zonder Java te installeren

Java + Mustang CLI installeren is prima voor een eenmalige check. Voor doorlopende verification — elke gegenereerde invoice, elke CI run die e-invoice compliance assert — is het onnodige frictie.

gpdf.com/validator/ draait Mustang in de browser:

1. Sleep uw Factur-X / ZUGFeRD PDF naar de upload zone.
2. De validator extraheert embedded XML en draait Mustangs Schematron engine (compiled to JavaScript / WebAssembly, running in the Cloudflare Worker).
3. Het Mustang report komt naast het PDF/A-3 report van veraPDF terug, omdat beide layers moeten slagen.
4. Download het JSON report als QA evidence.

Geen login. Geen quota. Hetzelfde type Mustang dat u via Maven zou installeren, maar als gratis public service.

TL;DR

Mustang flagt 5 common failure modes; meestal betekent dat dat het bestand is generated door een tool die geen fully-conformant Factur-X / ZUGFeRD PDF/A-3 emit. gPdf E-invoice API emit er een in één call. validator verifieert het resultaat met Mustang + veraPDF parallel.

De meeste bugs die Mustang vangt zitten in de wrapper of AFRelationship, niet alleen in XML semantics. Het bestand correct genereren is het grootste deel van het werk; validator is het receipt dat dat bewijst.