Leggere lo stato attuale di una fattura
- Nella sandbox
In parole semplici
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}$La fattura.
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 GET "https://example.com/invoices/inv_bd8bc8b276f38643f1c0f24f" \ -H "Authorization: Bearer <your-api-key>"{ "invoice_ref": "CAPTURE-JSON-1790961440", "environment": "sandbox", "document_sha256": "45f857890231e9bc6e73c1ec1e53bc01e7b030f84068b324bdd9ef42b88322bc", "route": "DE-XRECHNUNG", "updated_at": "2026-10-06T19:49:02.676Z", "documents": [ { "sha256": "45f857890231e9bc6e73c1ec1e53bc01e7b030f84068b324bdd9ef42b88322bc", "kind": "canonical", "href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/canonical" }, { "sha256": "ad122fe72dc6f04b2de6b6bbc01fcb7e46e33116b12e3bbb02a569cde3f10106", "kind": "manifest", "href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/manifest" }, { "sha256": "941fd5005aa03586a7bf23f3039c6d15e38220879d46690f9199a494e35fdc11", "kind": "validation-report", "href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/validation-report" }, { "sha256": "251a52fec3bdd44555a7396a1567d62c5ada3e3b7d002bb757d6b50e347c2e90", "kind": "xrechnung-ubl", "href": "/invoices/inv_936a93e38de84e7b0a1d7681/documents/xrechnung-ubl" } ], "client": "acme-srl", "created_at": "2026-10-06T19:49:01.621Z", "id": "inv_936a93e38de84e7b0a1d7681", "state": "ready", "invoice_number": "DOC-mux3dlqm"}Fermare una fattura non ancora inviata POST
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.
Scaricare un documento generato o la ricevuta del canale GET
Tipi: canonical (il JSON come ricevuto), erp-export (un export dell’ERP come l’ERP lo ha inviato), il file come inviato (ubl, cii, fa3, pdf), il documento generato (xrechnung-ubl per la Germania, altrimenti ubl o fa3), validation-report e manifest (lo SHA-256 dei byte che vanno al canale e i livelli che li hanno controllati). I quattro tipi JSON sono serviti come application/json. L’ETag è lo SHA-256.