DEV Community

S-Data
S-Data

Posted on

Fattura elettronica XML: gli errori più comuni che fanno scartare il file dallo SdI (e come evitarli)

#xml #italy #programming #tutorial

Chi genera fatture elettroniche da PDF o da Excel scopre presto che «produrre un XML» e «produrre un XML che lo SdI accetta» sono due lavori diversi. Qui metto in ordine i motivi di scarto che un convertitore può provocare, con codici e significati presi dai documenti ufficiali.

Fonti usate: Allegato A – Specifiche tecniche versione 1.9.1 (Agenzia delle Entrate), Elenco dei controlli versione 2.0 (fatturapa.gov.it) e lo schema Schema_VFPR12 versione 1.2.3. I link sono in fondo.

Due livelli di controllo, non uno

  1. Validazione dello schema (XSD). Controlla struttura, ordine degli elementi, tipi e formati. Un file che non la supera è, in pratica, «non conforme al formato»: 00200, e nel messaggio lo SdI indica il punto preciso. Se gli errori di formato sono più di 50, lo SdI si ferma con il 00201.
  2. Controlli di contenuto. Coerenza dei numeri, identificativi fiscali, codice destinatario, unicità. Qui lo schema non ti aiuta: un file può essere valido sull'XSD e venire scartato lo stesso.

Per questo conviene validare in locale sull'XSD, ma non fermarsi lì.

Codici di scarto da conoscere

Significati come da Elenco controlli v2.0 e Allegato A 1.9.1:

Codice Significato
00200 File non conforme al formato (il messaggio indica la non conformità puntuale)
00300 / 00301 / 00305 Identificativo fiscale non valido: IdCodice del trasmittente (00300), del cedente/prestatore (00301), del cessionario/committente (00305). Il controllo verifica la presenza in anagrafe tributaria; non si applica agli identificativi assegnati da autorità estere
00311 CodiceDestinatario non valido
00400 Natura assente con AliquotaIVA pari a zero
00401 Natura presente con AliquotaIVA diversa da zero (con l'eccezione del TipoDocumento TD16)
00404 Fattura duplicata: stesso cedente, stesso anno della data, stesso numero di una fattura già trasmessa e non scartata
00421 / 00422 / 00423 Imposta, ImponibileImporto e PrezzoTotale non calcolati secondo le regole delle specifiche
00424 AliquotaIVA non espressa in termini percentuali
00427 CodiceDestinatario di lunghezza non ammessa per il FormatoTrasmissione (7 caratteri con FPA12, 6 con FPR12)

Altri due: 00417 (del cessionario/committente deve esserci almeno uno tra partita IVA e codice fiscale) e 00425 (il Numero documento deve contenere almeno un carattere numerico).

Dove sbaglia un convertitore PDF/Excel → XML

Date. Nello schema Data è un xs:date: formato 2026-10-27. Una data letta dal PDF come 27/10/2026 non passa l'XSD (l'ho provato). La data non può nemmeno essere successiva alla ricezione da parte dello SdI (00403).

Decimali e arrotondamenti. Qui nascono molti scarti 00421–00423. Le regole:

  • PrezzoTotale deve essere uguale a (PrezzoUnitario ± ScontoMaggiorazione) × Quantita, con tolleranza di ±1 centesimo (00423);
  • Imposta è AliquotaIVA × ImponibileImporto / 100, arrotondata alla seconda cifra decimale (per difetto se la terza è inferiore a 5, per eccesso se uguale o maggiore), tolleranza ±1 centesimo (00421);
  • ImponibileImporto per ogni aliquota è la somma dei PrezzoTotale delle righe con quell'aliquota (più contributo cassa e arrotondamento, se presenti), con tolleranza di ±1 euro (00422).

Nello schema Imposta e ImportoTotaleDocumento ammettono esattamente due decimali: 8.250 è respinto, 8.25 passa. PrezzoUnitario ne accetta da 2 a 8, la Percentuale di sconto solo 2. L'Agenzia stessa segnala nelle sue FAQ che il 00423 compare spesso con gli sconti quando il sistema di origine lavora con più decimali di quelli previsti dal tracciato. In un convertitore: calcola con tipi decimali (mai float), arrotonda come da specifica e confronta i totali ricostruiti con quelli del documento sorgente.

Aliquote e Natura. AliquotaIVA va scritta come 22.00, non 22 e non 0.22. Attenzione: 0.22 è valido per l'XSD, perché ha due decimali, ma non è «in termini percentuali» e lo SdI risponde 00424. Con aliquota 0.00 serve la Natura (00400), con aliquota diversa da zero non va messa (00401). I codici generici N2, N3 e N6 non sono più ammessi come natura dell'operazione (controllo 00445), ma l'XSD li accetta ancora: serve il sottocodice (per esempio N2.2).

Codice destinatario e PEC. Il CodiceDestinatario ha 7 caratteri per i privati (FPR12) e 6 per la PA. 0000000 si usa quando il destinatario riceve via PEC indicata in PECDestinatario o quando non si conosce il canale. XXXXXXX è solo per soggetti non residenti: con un IdPaese italiano del cessionario viene scartato con 00313. Un codice a 6 caratteri in una fattura FPR12 supera l'XSD (che accetta 6–7 caratteri) ma fa scattare il 00427.

Partita IVA e codice fiscale. L'esistenza la verifica lo SdI (00300, 00301, 00305), non lo schema. Dal PDF possono arrivare spazi, prefissi «IT» ripetuti o zeri persi: normalizza prima di scrivere IdCodice.

Ordine degli elementi. Lo schema è una sequenza: mettere PrezzoUnitario prima di Quantita produce un errore (Element 'Quantita': This element is not expected). Se generi l'XML da un dizionario, non dare per scontato l'ordine delle chiavi.

Encoding e caratteri. Le descrizioni ammettono solo caratteri Basic Latin e Latin-1 Supplement: è, à passano, mentre il trattino lungo – e il simbolo €, comunissimi nel testo copiato da un PDF, vengono respinti dall'XSD. Sostituiscili prima di scrivere. Anche Numero è limitato a 20 caratteri Basic Latin.

Numero e duplicati. Il numero deve avere almeno una cifra (00425). Ritrasmettere lo stesso numero è un problema solo se la fattura precedente non è stata scartata (00404): dopo uno scarto, la stessa fattura corretta può essere inviata di nuovo con lo stesso numero.

Dimensioni e nome file. Il singolo file fattura non può superare 5 MB. Il nome segue IdPaese + codice trasmittente, underscore, progressivo alfanumerico di massimo 5 caratteri, ad esempio IT01234567890_00001.xml.

Un frammento corretto

Il blocco righe e riepilogo di una fattura TD01 con due aliquote (22% e operazione con natura N2.2). Ho validato il file completo da cui è estratto sull'XSD 1.2.3 con libxml2: l'esito riguarda solo lo schema. I controlli di contenuto dello SdI (anagrafe, destinatario) non si possono riprodurre in locale, e i dati sono inventati.

<DatiBeniServizi>
  <DettaglioLinee>
    <NumeroLinea>1</NumeroLinea>
    <Descrizione>Consulenza tecnica</Descrizione>
    <Quantita>3.00</Quantita>
    <UnitaMisura>ore</UnitaMisura>
    <PrezzoUnitario>12.50</PrezzoUnitario>
    <PrezzoTotale>37.50</PrezzoTotale>
    <AliquotaIVA>22.00</AliquotaIVA>
  </DettaglioLinee>
  <DettaglioLinee>
    <NumeroLinea>2</NumeroLinea>
    <Descrizione>Rimborso spese documentate</Descrizione>
    <PrezzoUnitario>100.00</PrezzoUnitario>
    <PrezzoTotale>100.00</PrezzoTotale>
    <AliquotaIVA>0.00</AliquotaIVA>
    <Natura>N2.2</Natura>
  </DettaglioLinee>
  <DatiRiepilogo>
    <AliquotaIVA>22.00</AliquotaIVA>
    <ImponibileImporto>37.50</ImponibileImporto>
    <Imposta>8.25</Imposta>
    <EsigibilitaIVA>I</EsigibilitaIVA>
  </DatiRiepilogo>
  <DatiRiepilogo>
    <AliquotaIVA>0.00</AliquotaIVA>
    <Natura>N2.2</Natura>
    <ImponibileImporto>100.00</ImponibileImporto>
    <Imposta>0.00</Imposta>
    <RiferimentoNormativo>Esempio di riferimento normativo</RiferimentoNormativo>
  </DatiRiepilogo>
</DatiBeniServizi>
Enter fullscreen mode Exit fullscreen mode

Per validare in locale basta qualche riga (serve lo schema scaricato dal sito dell'Agenzia):

from lxml import etree

schema = etree.XMLSchema(etree.parse("Schema_VFPR12_v1.2.3.xsd"))
doc = etree.parse("fattura.xml")
if not schema.validate(doc):
    for e in schema.error_log:
        print(e.line, e.message)
Enter fullscreen mode Exit fullscreen mode

Nota: lo schema importa lo schema xmldsig del W3C; se la rete non è disponibile, scaricane una copia e sostituisci il percorso nell'import.

Checklist finale

  • Date in formato AAAA-MM-GG, non successive all'invio.
  • Importi con punto decimale, due decimali dove richiesto; calcoli con tipi decimali.
  • Ricalcola PrezzoTotale, Imposta e ImponibileImporto e verifica le tolleranze prima di scrivere.
  • AliquotaIVA in percentuale (22.00); Natura solo con aliquota zero, e mai N2, N3 o N6 generici.
  • CodiceDestinatario di 7 caratteri per FPR12; 0000000 con PECDestinatario; XXXXXXX solo per non residenti.
  • Partita IVA e codice fiscale normalizzati; almeno uno dei due per il cessionario.
  • Elementi nell'ordine dello schema.
  • Testo ripulito dai caratteri fuori da Basic Latin e Latin-1 (trattini lunghi, €).
  • Numero con almeno una cifra, massimo 20 caratteri; file sotto 5 MB; nome file corretto.
  • Validazione sull'XSD ufficiale aggiornato alla versione in vigore, a ogni cambio di specifiche.

Per approfondire

Se ti serve generare questi file da documenti esistenti, qui trovi come funziona un convertitore da PDF a XML per la fattura elettronica; il quadro generale è nella pagina sulla fatturazione elettronica. S-Data sviluppa convertitori su misura: se il tuo caso non rientra negli strumenti già pronti, se ne può parlare.

Fonti ufficiali

Top comments (0)