Specifiche tecniche fattura elettronica 1.9.1: guida sviluppatori

Le 4 modifiche tecniche in v1.9.1 (vs v1.9)

Dallo "Stato del documento" dell'Allegato A (pag. 9), la versione 1.9.1 introduce quattro variazioni rispetto alla v1.9 del 31/01/2025:

1. Nuovo codice errore 00327 — controllo su CodiceFiscale di partecipante a Gruppo IVA (cessionario).
2. Aggiornamento procedure di accreditamento per i canali Web Service e SFTP (paragrafo 1.5.3).
3. Nuova codifica ESENZSPORT nel blocco <AltriDatiGestionali> per redditi sportivi dilettantistici in esenzione.
4. Aumento del numero massimo di codici destinatario richiedibili per canale accreditato (ora fino a 300).

Lo schema XSD della fattura ordinaria (Schema_VFPR12_v1.2.3.xsd) e di quella semplificata (Schema_VFSM10_v1.0.2.xsd) sono stati riemessi con versione incrementale ma senza modifiche di tipi né enumerations: i 4 cambiamenti sono tutti a livello di controlli semantici lato SDI, non di sintassi XML.

1. Errore 00327 — Gruppo IVA del cessionario

Si aggiunge ai controlli storici 00321/00322/00325/00326 sull'appartenenza di CF/P.IVA a un gruppo IVA. La descrizione ufficiale (Allegato A pag. 122):

Codice: 00327
Fattura ordinaria : 1.4.1.2 <CodiceFiscale> di gruppo IVA
                    non riferito ad un partecipante,
                    in assenza di <IdFiscaleIVA> di gruppo IVA
Fattura semplificata: 1.3.1.2 <CodiceFiscale> di gruppo IVA
                      non riferito ad un partecipante,
                      in assenza di <IdFiscaleIVA> di gruppo IVA

Logica di scarto: in assenza di partita IVA del cessionario/committente, se il CodiceFiscale valorizzato coincide con quello di un Gruppo IVA invece che con quello di una sua società partecipante, lo SDI scarta. Il CF deve essere quello della singola società partecipante al gruppo.

XPath del campo controllato:

• Ordinaria: /p:FatturaElettronica/FatturaElettronicaHeader/CessionarioCommittente/DatiAnagrafici/CodiceFiscale (posizione 1.4.1.2 nella tabella).
• Semplificata: /p:FatturaElettronicaSemplificata/FatturaElettronicaHeader/CessionarioCommittente/IdentificativiFiscali/CodiceFiscale (posizione 1.3.1.2).

Impatto codice gestionale: l'anagrafica cliente di un gestionale deve distinguere il CF del gruppo (per liquidazione e dichiarazioni) dal CF della partecipante (per la fatturazione). In molti gestionali questi due CF coincidono nello stesso record "cliente gruppo"; con la 1.9.1 vanno gestiti come due campi distinti, o si rischia uno scarto sistematico.

→ Casi clinici e mapping anagrafici per 00327

2. Codifica ESENZSPORT in AltriDatiGestionali

Per fatture che certificano compensi di lavoro sportivo dilettantistico ex art. 36, comma 6, D.Lgs. 36/2021 (con esenzione dall'imponibile fino a 15.000 € annui), si introduce un nuovo valore convenzionale per TipoDato:

<AltriDatiGestionali>
  <TipoDato>ESENZSPORT</TipoDato>
  <RiferimentoTesto>...</RiferimentoTesto>  <!-- opzionale -->
  <RiferimentoNumero>...</RiferimentoNumero> <!-- importo esente -->
  <RiferimentoData>...</RiferimentoData>     <!-- opzionale -->
</AltriDatiGestionali>

Posizione nel tracciato (Allegato A pag. 54):2.2.1.16 — figlio diretto di DatiGeneraliDocumento oppure di DettaglioLinee.

XSD invariato: il tipo di TipoDato è String10Type (stringa libera fino a 10 caratteri), già ammette "ESENZSPORT". Nessuna modifica al parser; cambia solo l'handler downstream che deve riconoscere il valore per alimentare le visualizzazioni nei portali consultazione e nelle dichiarazioni precompilate.

Valori storici riconosciuti su TipoDato (per riferimento, già nella v1.9): INVCONT, INTENTO, F24, NellAnno, AnniPreced, NB1, NB2, NB3, N.DOC.COMM, ALI-COMP, NO-COMP, OCC34BIS. La 1.9.1 aggiunge ESENZSPORT a questa lista.

→ Casi d'uso ESENZSPORT (ASD/SSD, athleti, tecnici)

3. Procedure di accreditamento WS/SFTP aggiornate

Il paragrafo 1.5.3 dell'Allegato A consolida i 6 passi del processo di accreditamento di un canale telematico (immutati nei contenuti, ma riorganizzati e armonizzati con la UX del nuovo Sistema di Accreditamento):

1. Accesso a accreditamento.fatturapa.gov.it con SPID, CIE o CNS.
2. Inserimento dei dati anagrafici sottoscrittore e dei dati del canale WS/SFTP da accreditare.
3. Solo per il canale WS: upload del CSR (Certificate Signing Request) per la generazione dei certificati client.
4. Svolgimento dei test di interoperabilità.
5. Presa visione e accettazione dell'Accordo di Servizio.
6. Richiesta del passaggio in produzione.

Genesi CSR — esempio OpenSSL minimale:

openssl req -new -newkey rsa:2048 -nodes \
  -keyout sdi-client.key \
  -out sdi-client.csr \
  -subj "/C=IT/ST=...//L=.../O=Ragione Sociale/CN=<CodiceFiscale>"

→ Procedura accreditamento dettagliata (CSR, KPI, troubleshooting)

4. Limite codici destinatario portato a 300 per canale

Allegato A, pag. 24: "Per i canali accreditati in ricezione, una volta effettuato il passaggio in produzione [...] l'utente può richiedere dei codici destinatario (fino ad un massimo di 300 codici)."

Impatto pratico:

• Le software house che agiscono come hub di ricezione per più clienti possono ora servire fino a 300 codici destinatario distinti per singolo canale accreditato (utile per multi-tenant).
• Le aziende multi-sede o con più ragioni sociali in gruppo possono assegnare un codice destinatario per sede/società senza dover accreditare canali aggiuntivi.
• Gestionali ERP che storicizzano codici destinatario clienti su anagrafica devono prevedere campo VARCHAR(7) — invariato — ma considerare l'aumento del cardinality lato dispatcher.

→ 300 codici destinatario: scenari multi-sede e routing

Checklist di rilascio

Da completare prima del 14 maggio 2026 in ambiente sandbox e in produzione:

• Aggiornare i file Schema_VFPR12_v1.2.3.xsd e Schema_VFSM10_v1.0.2.xsd in tutti gli ambienti (dev, staging, prod) e nei container Docker.
• Estendere l'enum/catalogo dei codici errore SDI con 00327 (descrizione + risoluzione lato utente).
• Aggiungere ESENZSPORT ai valori ammessi per il dropdown TipoDato dei moduli di fatturazione sportiva.
• Anagrafica cliente: campo separato CF gruppo IVA vs CF partecipante (per evitare 00327).
• Job di test end-to-end in sandbox per ognuna delle 4 novità (vedi casi A/A.bis/B/C/D nella guida sandbox).
• Aggiornamento documentazione cliente (release notes, changelog).
• Pianificare finestra di rollback 24h post-cutover: l'incompatibilità XSD impedisce hot-rollback al vecchio schema.

Modifiche XSD: cosa NON cambia

A scanso di equivoci, in 1.9.1 non cambiano:

• Le enumeration di TipoDocumentoType (resta TD01… TD29).
• Le enumeration di NaturaType (N1, N2.x, N3.x, N4, N5, N6.x, N7).
• Le enumeration di RegimeFiscaleType (RF01… RF20).
• Lo schema MessaggiFatturaTypes_v1.0 per ricevute, scarto, mancata consegna, attestazione.
• Il limite dimensionale del singolo file fattura (5MB).

Le modifiche strutturali (TD29, RF20, TD28 multi-uso) sono già in v1.9 (gennaio 2025): chi viene da una v1.8 o precedente deve gestire prima quel salto, poi la 1.9.1. → Diff completo 1.9 vs 1.9.1

Domande frequenti