Inviare un documento UBL o CII già pronto (pass-through)
- Nella sandbox
In parole semplici
Per gli ERP che già scrivono UBL o CII, oppure FA(3) per il canale KSeF. Non avviene alcuna mappatura: il servizio esegue
i validatori ufficiali del canale (per FA(3): l’XSD più le regole di KSeF sul file e sulle date) e invia il
file senza modificarlo. Un PDF Factur-X o ZUGFeRD passa dallo stesso endpoint
come application/pdf. L’XML viene letto con entità, DTD e accesso alla rete disattivati, e un file con un
DOCTYPE viene rifiutato (EI-XML-DTD) prima che un validatore lo legga, così come un file non ben formato
(EI-XML-SYNTAX) o che non è una fattura che il canale conosce (EI-XML-TYPE). Dalla 0.18.4 lo stesso file inviato di nuovo
per lo stesso cliente e canale è la fattura già conservata (duplicate_of), come su POST /invoices; non viene inviato nulla di nuovo.
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.
route*stringIl canale di trasmissione. Gli stessi valori di country_route negli eventi di stato.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringL’id del documento nell’ERP.
length <= 100Idempotency-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 <= 100body*stringAccettata per l’elaborazione.
application/json- response
id*stringstate*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"duplicate_of?|Impostato quando lo stesso documento era già stato accettato per questo cliente e canale; non viene inviato nulla di nuovo. Un invio terminato in rejected, validation_failed o cancelled non conta, quindi il file può essere inviato di nuovo. Dalla 0.18.5 vale anche per due richieste inviate nello stesso momento con chiavi diverse; una crea la fattura e l’altra risponde con duplicate_of.
links*route?RouteSolo quando il router ha scelto il canale.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Solo quando la richiesta ha omesso il canale.
"router"route_rule?stringLa regola del router che ha scelto il canale; scritta anche nel registro di audit come route_chosen.
"fr-domestic""fr-cross-border""pl-domestic""ro-domestic""be-domestic""de-domestic-peppol""de-domestic""cross-border-peppol"curl -X POST "https://example.com/invoices/xml?route=PL-KSEF&invoice_ref=INV-2026-0042" \ -H "Authorization: Bearer <your-api-key>" \ -H "Idempotency-Key: order-2026-0001" \ -H "Content-Type: application/xml" \ -d '<?xml version="1.0" encoding="UTF-8"?><Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/"><Naglowek><KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-10-01T05:44:07Z</DataWytworzeniaFa><SystemInfo>eurinvoice</SystemInfo></Naglowek><Podmiot1><DaneIdentyfikacyjne><NIP>1234567890</NIP><Nazwa>Wisła Systemy sp. z o.o.</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>ul. Floriańska 22</AdresL1><AdresL2>31-019 Kraków</AdresL2></Adres><DaneKontaktowe><Email>[email protected]</Email><Telefon>+48 12 345 67 89</Telefon></DaneKontaktowe></Podmiot1><Podmiot2><DaneIdentyfikacyjne><NIP>5213000000</NIP><Nazwa>Mazowiecka Hurtownia S.A.</Nazwa></DaneIdentyfikacyjne><Adres><KodKraju>PL</KodKraju><AdresL1>al. Jerozolimskie 100</AdresL1><AdresL2>00-807 Warszawa</AdresL2></Adres><JST>2</JST><GV>2</GV></Podmiot2><Fa><KodWaluty>PLN</KodWaluty><P_1>2026-09-26</P_1><P_1M>Kraków</P_1M><P_2>FV/2026/09/057</P_2><P_6>2026-09-25</P_6><P_13_1>25450.00</P_13_1><P_14_1>5853.50</P_14_1><P_15>31303.50</P_15><Adnotacje><P_16>2</P_16><P_17>2</P_17><P_18>2</P_18><P_18A>2</P_18A><Zwolnienie><P_19N>1</P_19N></Zwolnienie><NoweSrodkiTransportu><P_22N>1</P_22N></NoweSrodkiTransportu><P_23>2</P_23><PMarzy><P_PMarzyN>1</P_PMarzyN></PMarzy></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Wdrożenie KSeF 2.0</P_7><P_8A>LS</P_8A><P_8B>1</P_8B><P_9A>24000.00</P_9A><P_11>24000.00</P_11><P_12>23</P_12></FaWiersz><FaWiersz><NrWierszaFa>2</NrWierszaFa><P_7>Obsługa odrzuconych faktur</P_7><P_8A>MON</P_8A><P_8B>1</P_8B><P_9A>1450.00</P_9A><P_11>1450.00</P_11><P_12>23</P_12></FaWiersz><Platnosc><TerminPlatnosci><Termin>2026-10-10</Termin></TerminPlatnosci><FormaPlatnosci>6</FormaPlatnosci><RachunekBankowy><NrRB>61109010140000071219812874</NrRB><SWIFT>WBKPPLPP</SWIFT></RachunekBankowy></Platnosc><WarunkiTransakcji><Zamowienia><DataZamowienia>2026-09-26</DataZamowienia><NrZamowienia>ZAM-2026-311</NrZamowienia></Zamowienia></WarunkiTransakcji></Fa><Stopka><Rejestry><PelnaNazwa>Wisła Systemy sp. z o.o.</PelnaNazwa><KRS>0000123456</KRS></Rejestry></Stopka></Faktura>'{ "links": { "self": "/invoices/inv_d249e33382ce2911876b7295", "events": "/invoices/inv_d249e33382ce2911876b7295/events" }, "id": "inv_d249e33382ce2911876b7295", "state": "queued"}Inviare una fattura o una nota di credito come JSON canonico POST
Il servizio controlla subito il documento rispetto al modello canonico e ai controlli preliminari, e risponde 422 se uno dei due fallisce. Tutto il resto avviene in modo asincrono (generazione, validazione ufficiale, invio al canale, stati) e viene riportato con gli eventi di stato. L’invio corretto di una fattura scartata usa lo stesso invoice_ref e una nuova Idempotency-Key; il servizio collega i tentativi. In produzione un export dell’ERP viene letto solo quando le impostazioni del connettore del cliente contengono il suo venditore e i suoi dati di pagamento, non l’esempio della mappatura: altrimenti 422 connector-settings-missing, con l’indicazione di ciò che manca. Una sandbox lo legge con l’esempio, come prima.
Cercare un codice di errore o di motivo GET
Restituisce la voce del catalogo per l’ID di una regola, un codice di errore di un canale o un codice motivo francese (ID e alias).