Inviare fatture elettroniche
Dal file FatturaPA all’esito SdI: cosa inviare, cosa salvare e come gestire una risposta incerta.
Preparare il documento#
POST /machine/invoices/outbound accetta JSON con due campi obbligatori:
| Campo | Contenuto |
|---|---|
filename | Nome originale, almeno cinque caratteri. Usa .xml o .xml.p7m secondo il contenuto. |
xmlBase64 | Base64 dei byte del file completo, senza prefisso data URL. Per un P7M codifica l’intera busta CAdES. |
POST /machine/invoices/outbound HTTP/1.1
x-api-key: <API_KEY>
Content-Type: application/json
{
"filename": "fattura.xml",
"xmlBase64": "<BASE64_DEL_FILE_COMPLETO>"
}Il valore di xmlBase64 nell’esempio è un segnaposto: deve contenere la codifica Base64 del file FatturaPA completo.
FttEl genera il nome per la trasmissione a SdI. Il nome originale resta in senderFilename; il nome di trasmissione è filename. Usa un nome originale riconoscibile e distinto per ciascuna operazione del gestionale, ma non considerarlo una chiave univoca imposta dal servizio.
Il documento deve contenere una data Data valida. Per le fatture ordinarie, la partita IVA del cedente deve corrispondere all’account. I documenti di reverse charge seguono controlli specifici: verifica il tipo documento e l’intestazione prima dell’invio.
I file CAdES vengono estratti per leggere l’XML. Per un XML FPA12 privo di firma XML, il servizio richiede la firma XAdES all’integrazione eSignature configurata. Un errore di firma può arrivare dopo la creazione del record: anche in caso di 422, verifica se la fattura è già stata memorizzata.
Interpretare la risposta#
Conserva id, filename, status, sdiIdentifier e error insieme all’identificativo dell’operazione nel gestionale. Un codice HTTP positivo non basta: se SdI restituisce un errore applicativo, la risposta può contenere PROCESSING_ERROR e un messaggio in error.
Esempio di risposta 201 Created:
{
"id": "invoice_123",
"filename": "IT12345678901A2026_00001.xml",
"status": "SENT",
"sdiIdentifier": "123456789",
"error": null
}| Stato | Come leggerlo |
|---|---|
TAKEN_IN_CHARGE | Record creato prima di completare l’invio. Una chiamata interrotta può lasciarlo in questo stato. |
SENT | Invio completato senza errore applicativo SdI; attendi le notifiche. |
PROCESSING_ERROR | Errore di elaborazione o invio: consulta risposta e dati persistiti prima di decidere un nuovo tentativo. |
DELIVERED | Ricevuta di consegna. |
NOT_DELIVERED | Notifica di mancata consegna. |
DELIVERY_IMPOSSIBLE | Attestazione di avvenuta trasmissione con impossibilità di recapito. |
DISCARDED | Scarto SdI: leggi il dettaglio XML della notifica. |
ACCEPTED / REFUSED | Esito del destinatario, rispettivamente EC01 / EC02. |
DEADLINE_EXPIRED | Notifica di decorrenza termini. |
Questi sono gli stati assegnati dai flussi correnti di invio e notifica. Il contratto include altri valori: gestisci uno stato sconosciuto senza interrompere la sincronizzazione. Gli stati non costituiscono un contatore progressivo; per una vista aggiornata rileggi la fattura via API.
Timeout, duplicati e nuovi tentativi#
- Registra nel gestionale l’operazione in corso prima del POST e impedisci invii concorrenti dello stesso documento.
- Se ricevi l’id, usalo per ogni controllo successivo.
- Se perdi la risposta, cerca il nome originale con
senderFilename. Confronta numero, data, direzione e documento; il nome da solo non garantisce unicità. - Se trovi un record, esamina stato e notifiche. Se non lo trovi, attendi e verifica ancora: la richiesta precedente potrebbe essere ancora in esecuzione.
- Se l’esito resta incerto, coinvolgi il gestore prima di autorizzare un nuovo invio. La ricerca non rende il POST idempotente.
GET /machine/invoices?direction=OUTBOUND&senderFilename=fattura.xml HTTP/1.1
x-api-key: <API_KEY>Dopo uno scarto, correggi il documento sulla base della notifica e gestisci esplicitamente l’eventuale nuova trasmissione. Evita retry automatici dei POST su timeout o 5xx.