gPdf
Blog

Validare ZUGFeRD con Mustang: cosa passa, cosa fallisce e perché

Mustang è il controllore di riferimento de facto per Factur-X / ZUGFeRD. Una guida agli errori comuni quando si incorpora XML CII in un PDF/A-3, e a come verificare prima dell'invio.

gPdf Engineering
#e-invoice#zugferd#factur-x#verifica

Se nel 2026 inviate fatture elettroniche a un cliente B2B tedesco, il file è conforme a ZUGFeRD oppure viene respinto in ricezione. Lo stesso vale in Francia con Factur-X. Il formato è un contenitore PDF/A-3 con XML CII EN 16931 allegato: generarlo da zero non è banale e verificarlo richiede un motore di riferimento.

Quel motore, in pratica, è Mustang (mustangproject.org): un progetto Java open source che estrae l’XML incorporato da un PDF/A-3 e lo verifica contro lo Schematron EN 16931. Mustang offre il supporto più profondo per ZUGFeRD e Factur-X tra gli strumenti open source, ed è quello usato da molti verificatori indipendenti.

Questo articolo passa in rassegna gli errori che Mustang segnala e un modo più rapido per eseguirlo.

Che cosa controlla davvero Mustang

Quando passate un PDF Factur-X o ZUGFeRD a Mustang, il controllo è grosso modo questo:

  1. Estrae il file incorporato. PDF/A-3 memorizza gli allegati nel name tree /EmbeddedFiles. Mustang cerca il nome file canonico (factur-x.xml per Factur-X, zugferd-invoice.xml per ZUGFeRD 2.x) e legge i byte.
  2. Controlla AFRelationship. Il file allegato deve essere dichiarato con AFRelationship="Alternative" secondo la base Factur-X / ZUGFeRD. Qualunque altro valore (Source, Data, Supplement) fallisce.
  3. Controlla namespace XMP e versione. Factur-X 1.0 usa urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#. ZUGFeRD 2.x usa urn:zugferd:pdfa:CrossIndustryDocument:invoice:2p0#. Un namespace o una stringa di versione errati fanno fallire il controllo.
  4. Analizza l’XML come Cross-Industry Invoice (CII). Deve essere XML ben formato e iniziare con l’elemento radice CII corretto (rsm:CrossIndustryInvoice).
  5. Esegue lo Schematron EN 16931. Qui sta la parte principale della verifica: circa 200 regole di business su semantica dei campi, codici obbligatori, calcolo dei totali, logica IVA, identificativi delle parti e così via.

Pass = la fattura è accettabile da qualunque sistema AP conforme a EN 16931 nell’UE. Fail = l’automazione AP del cliente respingerà la fattura in ricezione e il team AR dovrà gestire un’eccezione manuale.

I cinque errori più frequenti

Questi casi compaiono spesso nel lato Mustang del validator quando i team provano le prime fatture elettroniche.

1. AFRelationship errato

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

La specifica PDF consente diversi tipi di relazione per i file allegati. Factur-X / ZUGFeRD richiedono in modo specifico Alternative: l’XML allegato è una rappresentazione alternativa del contenuto visibile nel PDF. Se il vostro generatore PDF usa Data (predefinito in molte librerie), Mustang fallisce subito. Il PDF visivo viene comunque riprodotto correttamente, ma il contenuto strutturato resta invisibile al sistema AP.

2. Namespace XMP errato o mancante

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

Il pacchetto XMP del PDF deve dichiarare quale profilo Factur-X è in uso (per esempio MINIMUM, BASIC, EN 16931, EXTENDED) e quale nome file cercare. È facile dimenticarlo quando si scrive a mano il contenitore PDF/A-3; /api/v1/e-invoice/render di gPdf emette automaticamente questi metadati.

3. XML CII ben formato, ma Schematron EN 16931 non superato

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

È la parte più frequente dei fallimenti reali. L’XML è valido sul piano sintattico; falliscono le regole di business. Le regole Schematron EN 16931 hanno ID stabili (BR-01, BR-CO-25 e così via) che potete cercare nella specifica EN 16931. Le più comuni:

  • BR-01: la fattura deve avere un numero univoco.
  • BR-04: la fattura deve avere una data di emissione.
  • BR-05: la fattura deve avere un codice tipo documento.
  • BR-CO-25: le condizioni di pagamento sono richieste quando il tipo documento è “Commercial invoice”.
  • BR-Z-01: i codici categoria IVA devono essere uno tra S, Z, E, AE, K, G, O, L, M.

Correggete i dati sorgente, ricostruite il file e verificate di nuovo.

4. Il contenitore PDF/A non supera la verifica

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

È il caso in cui il controllo XML di Mustang passa, ma il contenitore PDF/A-3 sottostante fallisce. Causa comune: qualcuno ha scritto correttamente l’XML ma ha emesso un PDF ordinario invece di un PDF/A-3. Il file incorporato è presente, ma le regole del contenitore archivistico non sono rispettate. Il validatore su gpdf.com/validator/ lo intercetta eseguendo veraPDF in parallelo: l’errore PDF/A-3 appare nella colonna veraPDF mentre Mustang segnala il passaggio dell’XML.

5. Incoerenza tra codifica e dichiarazione

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.

È un problema sorprendentemente comune quando l’XML viene prodotto da uno strumento che emette un BOM UTF-8 e poi viene incorporato così com’è. La correzione: rimuovere il BOM prima dell’incorporazione. Il percorso e-invoice di gPdf normalizza questo caso.

Eseguire Mustang senza installare Java

Installare Java e la CLI di Mustang va bene per un controllo una tantum. Per verifiche continuative, ogni volta che generate una fattura o in ogni run CI che conferma la conformità e-invoice, è attrito evitabile.

gpdf.com/validator/ esegue Mustang nel browser:

  1. Trascinate il PDF Factur-X / ZUGFeRD nell’area di caricamento.
  2. Il validatore estrae l’XML incorporato ed esegue il motore Schematron di Mustang (compilato in JavaScript / WebAssembly, eseguito in Cloudflare Worker).
  3. Il report Mustang torna affiancato al report PDF/A-3 di veraPDF, perché entrambi i livelli devono passare.
  4. Scaricate il report JSON come evidenza QA.

Nessun login. Nessuna quota. Lo stesso Mustang che installereste via Maven, reso disponibile come servizio pubblico gratuito.

TL;DR

Mustang segnala 5 errori comuni; molti si riducono a “il file è stato generato da uno strumento che non emette un PDF/A-3 Factur-X / ZUGFeRD pienamente conforme”. La E-invoice API di gPdf ne emette uno in una sola chiamata. Il validator verifica il risultato con due motori (Mustang + veraPDF) in parallelo.

La maggior parte dei problemi che Mustang individua riguarda il contenitore o AFRelationship, non la sola semantica XML. Generare correttamente il file è gran parte del lavoro; il validatore è la ricevuta che dimostra che lo avete fatto.