gPdf render/edge
Blog

ZUGFeRD mit Mustang validieren: was besteht, was scheitert und warum

Mustang ist der De-facto-Reference-Checker für Factur-X / ZUGFeRD. Typische Fehler beim Einbetten von CII XML in PDF/A-3 und wie Sie vor dem Versand prüfen.

by gPdf Engineering-Team
#e-invoice#zugferd#factur-x#validation

Wenn Sie 2026 E-Rechnungen an einen deutschen B2B-Kunden senden, ist die Datei entweder ZUGFeRD-konform oder sie wird beim Empfang zurückgewiesen. In Frankreich gilt dasselbe für Factur-X. Das Format ist ein PDF/A-3-Wrapper mit angehängtem EN 16931 CII XML. Es von Grund auf zu erzeugen ist nicht trivial, und die Validierung braucht eine Referenz-Engine.

Diese Engine ist in der Praxis Mustang (mustangproject.org): ein Open-Source-Java-Projekt, das embedded XML aus einem PDF/A-3 extrahiert und gegen EN 16931 Schematron validiert. Mustang hat die tiefste Unterstützung für ZUGFeRD und Factur-X unter den offenen Tools und läuft in vielen unabhängigen Prüfern.

Dieser Beitrag zeigt die Failure Modes, die Mustang meldet, und eine schnellere Art, es auszuführen.

Was Mustang wirklich prüft

Wenn Sie Mustang ein Factur-X- oder ZUGFeRD-PDF geben, passiert ungefähr Folgendes:

  1. Embedded file extrahieren. PDF/A-3 speichert attachments im /EmbeddedFiles name tree. Mustang sucht den kanonischen Dateinamen (factur-x.xml für Factur-X, zugferd-invoice.xml für ZUGFeRD 2.x) und liest die bytes.
  2. AFRelationship prüfen. Die attached file muss gemäß Factur-X / ZUGFeRD baseline als AFRelationship="Alternative" deklariert sein. Alles andere (Source, Data, Supplement) ist ein Fail.
  3. XMP namespace und version prüfen. Factur-X 1.0 nutzt urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#. ZUGFeRD 2.x nutzt urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#. Falscher namespace oder version string scheitert.
  4. XML als Cross-Industry Invoice (CII) parsen. Das XML muss well-formed sein und mit dem korrekten CII root element (rsm:CrossIndustryInvoice) beginnen.
  5. EN 16931 Schematron ausführen. Das ist der Hauptteil: rund 200 business rules zu Feldsemantik, Pflichtcodes, Summenlogik, VAT logic, party identifiers usw.

Pass = die Rechnung ist für jedes EN 16931-konforme AP-System in der EU akzeptabel. Fail = die AP automation des Kunden weist die Rechnung beim Empfang ab und das AR team bekommt eine manual exception.

Die fünf häufigsten Failure Modes

Diese tauchen immer wieder im Mustang-Bereich von validator auf, wenn Teams ihre ersten E-Rechnungen testen.

1. Falsches AFRelationship

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

Die PDF-Spezifikation erlaubt mehrere relationship types für attachments. Factur-X / ZUGFeRD verlangen ausdrücklich Alternative: Das attached XML ist eine alternative Darstellung des sichtbaren PDF-Inhalts. Wenn Ihr PDF generator Data verwendet (Default in vielen libraries), fällt Mustang sofort durch. Das sichtbare PDF rendert weiterhin, aber der strukturierte payload ist für das AP-System nicht gültig.

2. XMP namespace falsch oder fehlend

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

Das XMP packet des PDF muss deklarieren, welches Factur-X profile vorliegt (MINIMUM, BASIC, EN 16931, EXTENDED) und welchen Dateinamen der Prüfer suchen soll. Beim handgeschriebenen PDF/A-3 wrapper wird das leicht vergessen; gPdf /api/v1/e-invoice/render emitted diese Felder automatisch.

3. CII XML ist well-formed, aber EN 16931 Schematron scheitert

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

Hier liegt der Großteil echter Fehler. Das XML ist syntaktisch gültig; die business rules scheitern. EN 16931 Schematron rules haben stabile IDs (BR-01, BR-CO-25 usw.), die Sie in der Spezifikation nachschlagen können. Häufig:

  • BR-01: invoice braucht eine eindeutige Rechnungsnummer.
  • BR-04: invoice braucht ein Ausstellungsdatum.
  • BR-05: invoice braucht einen invoice type code.
  • BR-CO-25: payment terms sind Pflicht, wenn document type “Commercial invoice” ist.
  • BR-Z-01: VAT category codes müssen eines von S, Z, E, AE, K, G, O, L, M sein.

Korrigieren Sie die source data, bauen Sie neu und validieren Sie erneut.

4. Der PDF/A wrapper validiert nicht

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

Hier besteht Mustangs XML check, aber der zugrunde liegende PDF/A-3 wrapper fällt durch. Häufige Ursache: Das XML ist korrekt, aber ausgegeben wurde ein normales PDF statt PDF/A-3. Die embedded file ist vorhanden, aber die Archivregeln sind nicht erfüllt. Der Validator auf gpdf.com/validator/ erkennt das, indem er veraPDF parallel ausführt: PDF/A-3 fail erscheint in der veraPDF-Spalte, während Mustang XML pass meldet.

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.

Das ist überraschend häufig, wenn ein XML-Tool UTF-8 BOM emittiert und die bytes raw eingebettet werden. Lösung: BOM vor dem embedding entfernen. gPdf e-invoice endpoint normalisiert das.

Mustang ohne Java-Installation ausführen

Java + Mustang CLI ist für einen einmaligen Check in Ordnung. Für laufende Verifikation — jede generierte Rechnung, jeder CI run mit e-invoice compliance — ist es unnötige Reibung.

gpdf.com/validator/ führt Mustang im Browser aus:

  1. Ziehen Sie Ihr Factur-X / ZUGFeRD PDF in die upload zone.
  2. Der validator extrahiert embedded XML und führt Mustangs Schematron engine aus (compiled to JavaScript / WebAssembly, running in the Cloudflare Worker).
  3. Der Mustang report kommt neben dem PDF/A-3 report von veraPDF zurück, weil beide Ebenen bestehen müssen.
  4. Laden Sie den JSON report als QA evidence herunter.

Kein Login. Keine quota. Dasselbe Mustang-Prüfmodell wie bei einer Maven-Installation, nur als kostenloser öffentlicher Dienst.

TL;DR

Mustang meldet 5 common failure modes; meistens bedeutet das: Die Datei wurde von einem Tool erzeugt, das kein vollständig conformant Factur-X / ZUGFeRD PDF/A-3 emittiert. gPdf E-invoice API erzeugt es in einem Call. validator prüft das Ergebnis parallel mit Mustang + veraPDF.

Die meisten Bugs, die Mustang findet, betreffen wrapper oder AFRelationship, nicht nur XML semantics. Die Datei korrekt zu generieren ist der größte Teil der Arbeit; validator ist der Beleg dafür.