Inviare una fattura elettronica in Italia significa trasmettere un documento conforme allo standard FatturaPA al Sistema di Interscambio (SDI) dell’Agenzia delle Entrate.
Per software gestionali, applicazioni aziendali ed e-commerce, l’unico scenario ipotizzabile è l’utilizzo di un’API di fatturazione elettronica, che consente di integrare l’invio, la ricezione e la gestione delle notifiche direttamente nei flussi applicativi.
In questo articolo vediamo come funziona l’invio di una fattura elettronica via API allo SDI, quali sono le modalità di integrazione possibili e quali aspetti tecnici è importante considerare.
Il flusso di invio di una fattura elettronica via API
Indipendentemente dalla tecnologia utilizzata, il processo logico di invio è sempre lo stesso:
-
Preparazione dei dati della fattura
-
Trasmissione del documento allo SDI
-
Gestione delle notifiche di esito
Un’API di fatturazione elettronica si occupa di gestire l’interazione con lo SDI, evitando al gestionale di implementare direttamente protocolli, controlli e logiche normative complesse.
Preparazione del documento: XML o dati strutturati
Lo SDI accetta esclusivamente fatture in formato XML FatturaPA.
Un’API di fatturazione elettronica può però essere integrata in due modalità distinte, entrambe supportate.
Invio diretto dell’XML FatturaPA
In questo scenario:
-
il gestionale genera autonomamente l’XML FatturaPA
-
l’API riceve l’XML
-
l’API lo valida e lo trasmette allo SDI
Questa modalità è adatta quando:
-
il gestionale produce già XML conformi
-
esistono librerie interne consolidate
-
si desidera mantenere il controllo completo sul documento
Invio dei dati fattura in formato strutturato (JSON)
In alternativa, l’API può accettare i soli dati rilevanti della fattura (anagrafica, righe, importi, IVA, ecc.) in formato strutturato, ad esempio JSON.
In questo caso:
-
il gestionale invia i dati della fattura
-
l’API genera l’XML FatturaPA conforme
-
l’XML viene validato e inviato allo SDI
Questa modalità non sostituisce l’XML, ma rappresenta un livello di astrazione pensato per:
-
semplificare l’integrazione
-
ridurre la complessità del codice
-
evitare la gestione diretta dello standard XML
È particolarmente indicata per software gestionali ed ERP che vogliono concentrarsi sui dati di business senza legarsi alle specifiche tecniche della FatturaPA.
Validazione e invio allo SDI
Prima dell’invio, l’API esegue una serie di controlli:
-
verifica dei campi obbligatori
-
controlli di coerenza dei dati
-
validazioni formali previste dallo standard
Se la fattura è valida:
-
viene inviata allo SDI
-
viene restituito un identificativo di invio
In caso di errore:
-
l’API restituisce un errore strutturato
-
il gestionale può correggere i dati e ritentare l’invio
Questo approccio, oltre ad essere molto più rapido, consente di intercettare molti problemi prima che la fattura venga scartata dallo SDI.
Gestione delle notifiche SDI
Dopo l’invio, lo SDI restituisce diverse notifiche, tra cui:
-
ricevuta di consegna
-
mancata consegna
-
notifica di scarto
-
accettazione / decorrenza termini (per fatture inviata alla Pubblica Amministrazione)
L’API:
-
riceve le notifiche dallo SDI
-
le associa alla fattura inviata
-
le rende disponibili al gestionale in tempo reale
La gestione delle notifiche è uno degli aspetti più delicati della fatturazione elettronica e viene completamente demandata all’API.
Ricezione delle fatture elettroniche
Lo stesso modello si applica alla ricezione delle fatture passive.
L’API:
-
intercetta le fatture recapitate dallo SDI
-
le rende disponibili al gestionale
-
consente di ottenere il documento:
-
come XML originale
-
oppure come dati già decodificati in formato strutturato (JSON)
-
Questo permette al software di importare rapidamente le fatture ricevute senza dover implementare logiche di parsing XML complesse.
Quando utilizzare un’API di fatturazione elettronica
L’utilizzo di un’API è particolarmente indicato quando:
-
la fatturazione è integrata in un software
-
è necessario automatizzare l’invio e la ricezione
-
si gestiscono volumi medio-alti di fatture
-
è richiesta tracciabilità completa degli esiti
In questi contesti, l’API diventa il punto di collegamento stabile e affidabile tra il gestionale e lo SDI.
Conclusione
L’invio di fatture elettroniche allo SDI tramite API consente di integrare la fatturazione elettronica in modo strutturato, scalabile e conforme alla normativa.
Che si scelga di inviare XML FatturaPA già pronti o di trasmettere dati strutturati demandando all’API la generazione del documento, l’API permette di:
-
semplificare l’integrazione
-
ridurre la complessità tecnica
-
concentrarsi sullo sviluppo del proprio software
Una soluzione flessibile, pensata per adattarsi alle diverse esigenze di software house, aziende e piattaforme digitali.