E-INVOICE - Come verificare lo stato di una fattura elettronica? – fiskaly-support (IT)

Quando si crea un Record di fattura (TRANSACTION::INVOICE), viene creato contestualmente anche un Record di trasmissione (E_INVOICE::TRANSMISSION) per tracciare la consegna della fattura elettronica.

Nota: Un TRANSACTION::INVOICE nello stato COMPLETED e nella modalità FINISHED non implica necessariamente che la fattura elettronica sia stata accettata. È opportuno controllare i log diagnostici di entrambi i Record per identificare eventuali problemi.
Per E-INVOICE DE e BE, il Record TRANSACTION::INVOICE raggiunge lo stato COMPLETED non appena la fattura elettronica viene accettata per la trasmissione, mentre il Record E_INVOICE::TRANSMISSION riporta lo stato effettivo della consegna. Per questo motivo, gli stati dei due Record possono differire. Per E-INVOICE IT, gli stati dei due Record sono sempre allineati.

Passaggio 1: recupero del Record TRANSACTION::INVOICE

Alla creazione di un TRANSACTION::INVOICE, salvare l'id del record dalla risposta dell'API. Recuperarlo poi tramite:

GET /records/{{record_id}}

Nella risposta, controllare il campo content.logs:

Se contiene voci con "severity": "ERROR", la fattura non ha superato la validazione prima che venisse tentata la trasmissione. Per risolvere il problema, esaminare il messaggio di errore, correggere di conseguenza il payload della richiesta e creare un nuovo Record TRANSACTION::INVOICE con una nuova idempotency key, lo stesso numero di fattura, la stessa data e lo stesso contenuto.
Se content.logs non contiene voci ERROR, la validazione è stata superata e la fattura elettronica è stata inviata per la trasmissione. Procedere con il Passaggio 2.

Passaggio 2: recupero del Record E_INVOICE::TRANSMISSION

Nella risposta del TRANSACTION::INVOICE ottenuta al Passaggio 1, individuare il campo content.used_in.id. Questo è l'ID del Record E_INVOICE::TRANSMISSION. Recuperarlo tramite:

GET /records/{{content.used_in.id}}

Controllare il campo content.logs:

Se contiene voci ERROR, la fattura elettronica non è stata consegnata tramite il canale di fatturazione elettronica. Il campo message descrive il problema riscontrato.
- Se l'errore riguarda il contenuto della fattura, correggere di conseguenza il payload della richiesta e creare un nuovo Record TRANSACTION::INVOICE con una nuova idempotency key, lo stesso numero di fattura, la stessa data e lo stesso contenuto.
- Se l'errore indica un problema di rete o di infrastruttura, riprovare dopo una breve attesa.
Se il problema persiste, contatta il supporto fiskaly.
Se content.logs non contiene voci ERROR su entrambi i Record, la trasmissione potrebbe essere ancora in corso. La consegna della fattura elettronica viene gestita in modo asincrono:
- Per DE e BE, si completa in genere entro pochi secondi o minuti.
- Per IT, la risposta dello SDI può richiedere fino a 5 giorni.
Se la fattura elettronica non risulta ancora consegnata dopo diversi minuti per DE e BE, o dopo 5 giorni per IT, contatta il supporto fiskaly.

Lettura di una voce di log

Ogni voce di log contiene i seguenti campi:

Campo	Descrizione
`severity`	`ERROR` (un errore che ha impedito la consegna) oppure `WARNING` (un problema non critico, l'operazione è comunque proseguita).
`message`	Una descrizione leggibile del problema.
`code`	Un codice leggibile da un sistema per classificare il log.
`date`	La data e l'ora di creazione del log.

Esempio

[
  {
    "$": "Log@v1",
    "date": "2026-05-13T08:32:18.214995449Z",
    "message": "invalid Belgian VAT ID length '12'",
    "severity": "ERROR"
  },
  {
    "$": "Log@v1",
    "date": "2026-05-13T08:32:18.30059009Z",
    "message": "e_invoicing failed: code: invalid format.",
    "severity": "ERROR"
  }
]

Nota: i log WARNING sono a scopo informativo e non influiscono sulla trasmissione della fattura elettronica.