GetbeelDocs

Ciclo di vita SDI

Gli stati di una fattura emessa, cosa significa ogni esito dello SDI e cosa fare.

Una fattura emessa passa per pochi stati, sempre in avanti. Lo stato dice se la fattura è emessa: una cosa da sapere prima di inviarla di nuovo, perché una fattura emessa non si reinvia mai.

Stati

statusSignificatoEmessa?
draftBozza, modificabileNo
sendingL'XML è in preparazione e l'invio è in coda (solo chiavi live)No, non ancora
sentTrasmessa allo SDI, in attesa dell'esito (da pochi minuti fino a 5 giorni)In attesa
deliveredRicevuta di consegna (RC)Sì
not_deliveredRicevuta di impossibilità di recapito (MC): è nel cassetto fiscale del clienteSì
rejectedRicevuta di scarto (NS)No, mai
draft → sending → sent → not_delivered → delivered → rejected

Le transizioni vanno solo in avanti, in quest'ordine. Una ricevuta che arriva in ritardo o due volte non riporta mai indietro una fattura: un sent arrivato dopo un delivered viene ignorato. not_delivered può ancora diventare delivered, e una fattura consegnata può ancora diventare rejected quando una Pubblica Amministrazione la rifiuta. Le date dello SDI senza fuso orario vengono lette come ora italiana (Europe/Rome).

Con una chiave di test, POST /invoices/{id}/send risponde subito con sent e l'esito arriva qualche secondo dopo dalla sandbox. Con una chiave live risponde 202 con sending.

Ogni esito

Consegnata (RC) → delivered

Lo SDI ha recapitato la fattura all'indirizzo telematico del cliente. La fattura è emessa e la data di esigibilità dell'IVA è quella della fattura.

Non consegnata (MC) → not_delivered

Lo SDI ha fatto i controlli ma non ha potuto recapitare il file: il canale del cliente non era attivo, oppure il codice destinatario era 0000000 senza un indirizzo registrato. Ha messo la fattura nell'area riservata del cliente in "Fatture e Corrispettivi" (il cassetto fiscale), dalla data che trovi in sdi.available_since.

Una fattura non consegnata (MC): risulta emessa, è nel cassetto fiscale dalla data indicata e non va inviata di nuovo.

  • La fattura è emessa. Non inviarla di nuovo: lo SDI scarterebbe la copia come duplicato (00404).
  • Avvisa il cliente per un'altra via (email, telefono) che la trova nella sua area riservata; per lui l'IVA è detraibile dalla presa visione. Una copia di cortesia via email (POST /invoices/{id}/email) aiuta.
  • Per le prossime fatture chiedigli il codice destinatario o la PEC.
  • Per un'autofattura (TD16–TD19) il destinatario è la tua azienda: la trovi nel tuo cassetto fiscale. Per riceverle direttamente, registra un indirizzo telematico in "Fatture e Corrispettivi" (vedi codice destinatario).

Scartata (NS) → rejected

Uno o più controlli dello SDI non sono passati. La fattura si considera mai emessa.

Una fattura scartata dallo SDI: il codice di errore, la sua descrizione, la regola per reinviarla e il pulsante Correggi e reinvia.

  • sdi.errors elenca i codici con la descrizione dello SDI; sdi.error_codes solo i codici. Cosa significa ogni codice e come correggerlo: Codici di scarto SDI.

  • Correggi e inviala di nuovo con lo stesso numero e la stessa data, preferibilmente entro 5 giorni dalla notifica di scarto. Il nuovo invio ha un nuovo nome file, e lo SDI non lo considera un duplicato perché il primo era stato scartato.

  • Riapri, correggi, reinvia:

    1. POST /invoices/{id}/reopen la riporta in draft con lo stesso numero e la stessa data (nell'app: Correggi e reinvia; in MCP: reopen_rejected_invoice). sdi.errors resta visibile finché non viene reinviata.
    2. PATCH /invoices/{id} corregge quanto indicato in sdi.errors (Fatturazione; MCP update_invoice_draft).
    3. POST /invoices/{id}/send la invia di nuovo, con un Idempotency-Key così un nuovo tentativo non conta due volte.

    Con qualsiasi altro stato la risposta è 409 invoice_not_rejected. Con le chiavi di test si riaprono allo stesso modo gli scarti della sandbox.

curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/reopen \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
curl -X PATCH https://www.getbeel.com/api/v1/invoices/$INVOICE \
  -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"customer": {"denominazione": "Rossi S.r.l.", "partita_iva": "01234567890", "codice_destinatario": "M5UXCR1", "address": "Via Roma 1", "postal_code": "20121", "city": "Milano", "province": "MI"}}'
curl -X POST https://www.getbeel.com/api/v1/invoices/$INVOICE/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY" -H "Idempotency-Key: $(uuidgen)"
  • Il rifiuto di una Pubblica Amministrazione dopo la consegna (notifica di esito) compare oggi anche come rejected, ma non è uno scarto dello SDI: la fattura era stata consegnata. In quel caso non applicare la regola del reinvio e chiedi al commercialista come rettificarla.
  • Per le fatture live, getbeel può tentare da solo una correzione dell'XML e reinviarlo (al massimo 3 volte): la fattura torna sent con un nuovo invio, oppure torna in bozza da correggere a mano.

Duplicato di una fattura emessa (00404 su una fattura inviata)

Lo SDI scarta con 00404 ("Fattura duplicata") un file con lo stesso cedente, lo stesso anno e lo stesso numero di un documento che ha già accettato. Se capita a una fattura che era stata inviata, vuol dire che lo SDI ha già accettato una copia precedente: la fattura è emessa.

Una fattura scartata come duplicato (00404) di una copia già accettata: risulta già emessa e resta bloccata.

  • getbeel non la porta a rejected: resta sent (o lo stato che aveva), con 00404 in sdi.error_codes e sdi.errors. Nessun evento webhook.
  • Non rigenerarla e non reinviarla: ogni nuovo invio verrebbe di nuovo scartato con 00404.
  • L'assistenza collega l'invio accettato. Nei registri IVA il documento conta come emesso, segnato da verificare (needs_review).

Per le autofatture TD16–TD20, TD22, TD23, TD28 e TD29 il controllo di unicità si fa sul cessionario (la tua azienda).

In attesa → sent

Lo SDI ha il file e non ha ancora risposto. I controlli e la consegna richiedono da pochi minuti fino a 5 giorni quando lo SDI è molto carico. Non reinviare una fattura sent: aspetta l'esito.

Cosa mostrano web, API e MCP

EsitoWeb (badge)API status e sdiMCP (get_invoice, list_invoices)Webhook
In preparazioneInvio al SDI...sendingLo stesso JSON dell'API—
In attesaInviata al SDIsentCome l'APIinvoice.sent
RCConsegnatadeliveredCome l'APIinvoice.delivered
MCEmessa · nel cassetto fiscalenot_delivered, sdi.available_sinceCome l'API: "issued, never resend"invoice.not_delivered
NSScartata, con Correggi e reinviarejected, sdi.errorsCome l'API: "fix sdi.errors and resend"invoice.rejected
00404 su fattura inviataGià emessa · duplicato (bloccata)sent con 00404 in sdi.error_codesCome l'API: "already issued, do not resend"—

L'elenco delle fatture emesse con lo stato SDI di ciascuna: bozza, inviata, consegnata, emessa nel cassetto fiscale, scartata, già emessa (duplicato).

  • Web. Il dettaglio della fattura spiega l'esito con le fonti ufficiali: per MC la data di messa a disposizione e "Non va inviata di nuovo"; per NS i codici con la descrizione e la regola del reinvio; per 00404 "Già emessa: lo SDI ha una copia accettata".
  • API. GET /invoices/{id} e GET /invoices?status=… (vedi il riferimento).
  • MCP. Gli strumenti list_invoices e get_invoice restituiscono lo stesso JSON, e la loro descrizione spiega all'assistente ogni stato, così non propone mai di reinviare una fattura emessa. Esempio: Server MCP.

Webhook

Ogni cambio di stato invia un evento con la fattura completa in data.object:

EventoNuovo stato
invoice.sentsent
invoice.delivereddelivered
invoice.not_deliverednot_delivered
invoice.rejectedrejected

Un evento per transizione: una ricevuta duplicata o in ritardo non ne genera un altro. Il 00404 di una fattura già emessa non cambia stato e non invia eventi. Rileggi sempre lo stato con GET /invoices/{id} se ti serve quello attuale.

Inviare due volte non crea un duplicato

  • Idempotency-Key. Ripetere POST /invoices/{id}/send con la stessa chiave restituisce la prima risposta senza un secondo invio (Idempotenza).
  • Un solo invio per bozza. L'invio prende la bozza in modo atomico: una seconda richiesta, anche senza chiave, riceve 409 invoice_send_in_progress o 409 invoice_not_draft prima di qualsiasi chiamata allo SDI.
  • Esiti incerti. Se un invio finisce senza risposta certa (timeout, errore 5xx, rete), getbeel cerca il documento presso il canale di trasmissione prima di riprovare: se lo SDI l'ha già ricevuto ne registra l'identificativo invece di inviarlo di nuovo.
  • Le autofatture seguono la stessa regola: l'invio prende il documento in modo atomico e il canale viene interrogato solo dopo un esito incerto.

Fonti

  • Agenzia delle Entrate, La fattura elettronica e i servizi gratuiti, dicembre 2025: p. 16 (controlli dello SDI, duplicati, tempi fino a 5 giorni), p. 17 (ricevuta di scarto, reinvio con stessa data e numero e nuovo nome file; ricevuta di consegna), p. 18 (impossibilità di recapito, data di messa a disposizione, fattura emessa per il fornitore, scarto = fattura mai emessa), pp. 19–20 (registrazione dell'indirizzo telematico).
  • Agenzia delle Entrate, circolare 13/E del 2 luglio 2018, § 1.6, pp. 11–12: la fattura scartata va preferibilmente reinviata entro cinque giorni dalla notifica di scarto con la data e il numero del documento originario.
  • Agenzia delle Entrate, Allegato A, Specifiche tecniche versione 1.9.1 (31 marzo 2026), Appendice 1, "Verifiche di unicità della fattura", pp. 122–123: codici 00404 e 00409, controllo sul cessionario per TD16–TD20, TD22, TD23, TD28, TD29.
  • fatturapa.gov.it, documentazione SDI: specifiche tecniche ed elenco dei controlli.

In questa pagina