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

Als u in 2026 e-facturen naar een Duitse B2B-klant stuurt, is het bestand ZUGFeRD-conform of het wordt bij ontvangst geweigerd. In Frankrijk geldt hetzelfde voor Factur-X. Het formaat is een PDF/A-3-omhulsel met een EN 16931 CII XML-bestand als bijlage. Dat vanaf nul genereren is niet triviaal, en verifiëren vraagt om een referentie-engine.

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

Dit artikel loopt door de fouttypen die Mustang meldt en laat zien hoe u die sneller kunt controleren.

Wat Mustang echt controleert

Wanneer u een Factur-X- of ZUGFeRD-PDF aan Mustang geeft, gebeurt grofweg het volgende:

1. Het ingesloten bestand extraheren. PDF/A-3 bewaart bijlagen 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 uit.
2. AFRelationship controleren. Het bijgevoegde bestand moet volgens de Factur-X / ZUGFeRD-baseline AFRelationship="Alternative" declareren. Elke andere waarde (Source, Data, Supplement) faalt.
3. XMP-namespace en versie controleren. Factur-X 1.0 gebruikt urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#. ZUGFeRD 2.x gebruikt urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#. Een verkeerde namespace of versietekenreeks faalt.
4. De XML parsen als Cross-Industry Invoice (CII). Het moet geldige XML zijn en beginnen met het juiste CII-root-element (rsm:CrossIndustryInvoice).
5. EN 16931 Schematron draaien. Dit is het grootste deel van de validatie: ongeveer 200 bedrijfsregels over veldsemantiek, verplichte codes, totalenberekeningen, btw-logica, partij-identificatoren, enzovoort.

Geslaagd betekent dat de factuur acceptabel is voor elk EN 16931-conform AP-systeem in de EU. Gefaald betekent dat de AP-automatisering van uw klant de factuur bij ontvangst weigert en het AR-team een handmatige uitzondering krijgt.

De vijf fouttypen die we het vaakst zien

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

1. Verkeerde AFRelationship

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

De PDF-specificatie staat meerdere relatiecategorieën toe voor bijgevoegde bestanden. Factur-X / ZUGFeRD vereisen specifiek Alternative: de bijgevoegde XML is een alternatieve representatie van de zichtbare PDF-inhoud. Als uw PDF-generator Data gebruikt, wat in veel bibliotheken de standaard is, faalt Mustang direct. De zichtbare PDF rendert nog steeds correct, maar de gestructureerde data is onbruikbaar voor het AP-systeem.

2. Verkeerde of ontbrekende XMP-namespace

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

Het XMP-pakket van de PDF moet declareren welk Factur-X-profiel dit is, bijvoorbeeld MINIMUM, BASIC, EN 16931 of EXTENDED, en welke bestandsnaam gezocht moet worden. Dit wordt snel gemist wanneer u het PDF/A-3-omhulsel met de hand schrijft; gPdf’s /api/v1/e-invoice/render-API geeft deze metadata automatisch mee.

3. CII XML is syntactisch geldig, 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 de fouten in productie. Uw XML is syntactisch geldig, maar de bedrijfsregels falen. EN 16931 Schematron-regels hebben stabiele ID’s (BR-01, BR-CO-25, enzovoort) die u in de EN 16931-specificatie kunt opzoeken. Veelvoorkomende voorbeelden:

• BR-01: de factuur moet een uniek factuurnummer hebben.
• BR-04: de factuur moet een uitgiftedatum hebben.
• BR-05: de factuur moet een factuurtypecode hebben.
• BR-CO-25: betalingsvoorwaarden zijn vereist wanneer het documenttype “Commercial invoice” is.
• BR-Z-01: btw-categoriecodes moeten een van S, Z, E, AE, K, G, O, L, M zijn.

Corrigeer de brondata, bouw opnieuw en valideer opnieuw.

4. Het PDF/A-omhulsel valideert niet echt

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

Dit is de situatie waarin Mustangs XML-controle slaagt, maar het onderliggende PDF/A-3-omhulsel faalt. De gebruikelijke oorzaak: iemand heeft de XML correct geschreven, maar een gewone PDF uitgegeven in plaats van PDF/A-3. Het ingesloten bestand is aanwezig, maar de archiefregels voor het omhulsel zijn niet gehaald. De validator op gpdf.com/validator/ vangt dit door veraPDF parallel te draaien: een PDF/A-3-fout verschijnt in de veraPDF-kolom terwijl Mustang een XML-pass meldt.

5. Mismatch tussen encoding en declaratie

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.

Dit komt verrassend vaak voor wanneer XML wordt gegenereerd door een tool die een UTF-8 BOM schrijft en de bytes daarna raw worden ingesloten. De oplossing: verwijder de BOM vóór het insluiten. De gPdf e-invoice-API normaliseert dit.

Mustang draaien zonder Java te installeren

Java plus de Mustang CLI installeren is prima voor een eenmalige controle. Voor doorlopende verificatie, zoals elke gegenereerde factuur of elke CI-run die e-factuurconformiteit bewaakt, is die extra frictie niet nodig.

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

1. Sleep uw Factur-X / ZUGFeRD-PDF naar de uploadzone.
2. De validator extraheert de ingesloten XML en draait Mustangs Schematron-engine erop, gecompileerd naar JavaScript / WebAssembly en uitgevoerd in de Cloudflare Worker.
3. Het Mustang-rapport komt naast het PDF/A-3-rapport van veraPDF terug, omdat beide lagen moeten slagen.
4. Download het JSON-rapport als QA-bewijs.

Geen login. Geen quota. Dezelfde Mustang die u via Maven zou installeren, maar dan aangeboden als gratis publieke service.

TL;DR

Mustang markeert vijf veelvoorkomende fouttypen. De meeste daarvan komen neer op een bestand dat is gegenereerd door een tool die geen volledig conforme Factur-X / ZUGFeRD PDF/A-3 uitgeeft. De gPdf E-invoice API genereert zo’n bestand in één aanroep. De validator verifieert het resultaat parallel met twee engines: Mustang en veraPDF.

De meeste fouten die Mustang vindt zitten in het omhulsel of in AFRelationship, niet alleen in de XML-semantiek. Het bestand correct genereren is het grootste deel van het werk; de validator is het bewijsstuk dat laat zien dat dit is gelukt.