Fermare una fattura non ancora inviata
- Nella sandbox
In parole semplici
Funziona solo finché la fattura è received, validated o queued. Dalla 0.18.3, quando un invio è stato tentato e
la sua risposta è andata persa (un timeout o un 5xx), la fattura risulta submitting e un annullamento risponde 409
send-in-progress, perché il canale potrebbe averla; il worker la chiude come submitted o dead_letter. Una volta che
il canale ce l’ha, l’annullamento è un documento commerciale (una nota di credito, o un KOR in Polonia), non una chiamata API.
Dalla 0.18.5 l’annullamento di una fattura già annullata risponde 200 con la fattura, così un nuovo tentativo dopo una risposta
andata persa è sicuro. Dalla 0.18.6 la chiave dell’operatore può annullare una fattura dead_letter quando non è mai stata
fatta alcuna chiamata al canale per essa: sul canale non può esserci nulla, quindi lo stesso documento può essere inviato di nuovo. Quando
una chiamata è stata fatta, la risposta è 409 dead-letter-reached-rail, perché un invio la cui risposta è andata persa potrebbe essere lì: verificare
prima con il canale. La chiave di un cliente riceve 409 dead-letter; decide l’operatore.
apiKeyAuthorizationBearer <token>Inviare la chiave come token bearer: Authorization: Bearer <your-api-key>. Lo stato del servizio è l’unica chiamata che non richiede una chiave.
id*stringL’id della fattura restituito dalla chiamata di invio.
^inv_[A-Za-z0-9]{16,40}$Idempotency-Key*stringUna chiave unica per ogni richiesta logica (va bene un UUID). Conservata finché si conservano i dati del cliente. Con la chiave dell’operatore non può iniziare con client: (400), la forma con cui si conservano le chiavi dei clienti.
8 <= length <= 100Annullata prima dell’invio, una dead letter che non ha mai raggiunto il canale (chiave dell’operatore), oppure già annullata.
application/json- response
id*stringinvoice_ref*stringinvoice_number?stringroute*RouteIl canale di trasmissione. Gli stessi valori di country_route negli eventi di stato.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"environment*string"sandbox""production"state*InvoiceStateLo stato proprio del servizio per una fattura. Gli eventi di stato riportano il ciclo di vita visibile al partner;
queued e submitting sono passaggi interni tra validated e submitted. validation_failed significa che le regole ufficiali hanno rifiutato il documento; dalla
0.18.4 un controllo che non è stato eseguito (KOSIT-RUN, EI-PDF-CHECK) viene ritentato, poi termina in dead_letter con quel
codice. Una dead_letter tiene il documento, quindi lo stesso file risponde con duplicate_of; dalla 0.18.6
l’operatore può annullarne una per cui non è stata fatta alcuna chiamata al canale, e allora il file può partire di nuovo.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"legal_id?|Numero KSeF, indice di caricamento ANAF, ID del documento presso l’access point, ID della fattura sulla piattaforma francese.
buyer_status?string|nulldocument_sha256?|^[a-f0-9]{64}$attempts?array<>Invii precedenti dello stesso invoice_ref (ad esempio dopo uno scarto e una correzione).
errors?array<>documents?array<>created_at*stringdate-timeupdated_at*stringdate-timedeadline_at?stringUna scadenza indicativa per questa fattura, come ultimo istante dell’ultimo giorno consentito in UTC (leggere la parte della data come quel giorno): la data di emissione più cinque giorni lavorativi per la Romania (e-Factura), il giorno lavorativo successivo per la Polonia (KSeF offline24). I giorni si contano dal lunedì al venerdì e i giorni festivi non sono applicati, quindi la scadenza reale può essere successiva, mai anteriore; non è una consulenza legale. Indicata in ogni stato della fattura; non dice se la fattura era in tempo o in ritardo. Presente solo per quei due canali, e solo quando la fattura ha una data di emissione: POST /invoices con un invoice.issue_date, oppure, dalla 0.19.2, un file UBL (cbc:IssueDate) o un file FA(3) (Fa/P_1) inviato come XML o depositato nella cartella. Un PDF non ne ha, e la sua assenza non significa che non valga alcuna scadenza. Dalla 0.19.1.
date-timecurl -X POST "https://example.com/invoices/inv_bd8bc8b276f38643f1c0f24f/cancel" \ -H "Authorization: Bearer <your-api-key>" \ -H "Idempotency-Key: order-2026-0001"{ "invoice_ref": "FRESH-mux3dlqm-0", "environment": "sandbox", "document_sha256": "b341c81da6fe297787829a8c26fd4b25106b5b34e67482d38c1039651bbfed65", "route": "DE-XRECHNUNG", "updated_at": "2026-10-06T19:49:10.992Z", "client": "acme-srl", "created_at": "2026-10-06T19:49:10.816Z", "id": "inv_ae4d9834bf251353532fe5ee", "state": "cancelled", "invoice_number": "FRESH-mux3dlqm-0"}Conservare una credenziale, cifrata; il valore non viene mai restituito POST
Un processo conserva credenziali solo per il proprio ambiente. legal_entity ne lega una all’id del venditore per cui agisce (partita IVA, NIP, SIREN o id aziendale); una senza etichetta serve le altre fatture del cliente. La chiave admin di un cliente conserva solo per il proprio cliente.
Leggere lo stato attuale di una fattura GET
Successiva