Een afgewerkt UBL- of CII-document indienen (doorgifte)
- In de sandbox
In gewone woorden
Voor ERP's die al UBL of CII schrijven, of FA(3) voor het KSeF-verzendkanaal. Er vindt geen mapping plaats: de dienst voert
de officiële validators voor het verzendkanaal uit (voor FA(3): de XSD plus de bestands- en datumregels van KSeF) en verzendt het
bestand ongewijzigd. Een Factur-X- of ZUGFeRD-PDF gaat via hetzelfde eindpunt
als application/pdf. De XML wordt gelezen met entiteiten, DTD's en netwerktoegang uitgeschakeld, en een bestand met een
DOCTYPE wordt geweigerd (EI-XML-DTD) voordat een validator het leest, net als een bestand dat niet welgevormd is
(EI-XML-SYNTAX) of geen factuur is die het verzendkanaal kent (EI-XML-TYPE). Sinds 0.18.4 is hetzelfde bestand dat opnieuw wordt verzonden voor
de eindklant en het verzendkanaal de factuur die al is bewaard (duplicate_of), zoals bij POST /invoices; er wordt niets nieuws verzonden.
apiKeyAuthorizationBearer <token>Stuur uw sleutel als bearer-token: Authorization: Bearer <your-api-key>. De health-aanroep is de enige aanroep die geen sleutel vereist.
route*stringHet verzendkanaal van het land. Dezelfde waarden als country_route in statusberichten.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringDe eigen document-ID van het ERP.
length <= 100Idempotency-Key*stringEen unieke sleutel per logisch verzoek (een UUID is prima). Wordt bewaard zolang de gegevens van de eindklant worden bewaard. Met de sleutel van de beheerder mag hij niet beginnen met client: (400), de vorm waaronder sleutels van eindklanten worden bewaard.
8 <= length <= 100body*stringGeaccepteerd voor verwerking.
application/json- response
id*stringstate*InvoiceStateDe eigen status van de dienst voor een factuur. Statusberichten melden de levenscyclus zoals de partner hem ziet;
queued en submitting zijn interne stappen tussen validated en submitted. validation_failed betekent dat de officiële regels het document hebben geweigerd; sinds
0.18.4 wordt een controle die niet draaide (KOSIT-RUN, EI-PDF-CHECK) opnieuw geprobeerd en eindigt dan als dead_letter met die
code. Een dead_letter houdt zijn document vast, zodat hetzelfde bestand antwoordt met duplicate_of; sinds 0.18.6 kan de
beheerder er een annuleren waarvoor geen aanroep naar het verzendkanaal is gedaan, en dan kan het bestand opnieuw worden verzonden.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Gezet als hetzelfde document al was geaccepteerd voor deze eindklant en dit verzendkanaal; er wordt niets nieuws verzonden. Een indiening die eindigde als rejected, validation_failed of cancelled telt niet mee, zodat het bestand opnieuw kan worden verzonden. Sinds 0.18.5 geldt dit ook voor twee verzoeken die op hetzelfde moment worden verzonden, onder verschillende sleutels; een maakt de factuur aan en de ander antwoordt met duplicate_of.
links*route?RouteAlleen als de router het verzendkanaal koos.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Alleen als het verzoek het verzendkanaal wegliet.
"router"route_rule?stringDe regel van de router die het verzendkanaal koos; ook in het auditlogboek geschreven als 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"}Een factuur of creditnota als canonieke JSON indienen POST
De dienst controleert het document tegelijk tegen het canonieke model en de voorafgaande controles, en antwoordt 422 als een van beide faalt. Alles daarna verloopt asynchroon (opbouw, officiële validatie, verzending naar het verzendkanaal, statussen) en wordt gemeld via statusberichten. Een gecorrigeerde nieuwe indiening van een afgewezen factuur gebruikt dezelfde invoice_ref en een nieuwe Idempotency-Key; de dienst koppelt de pogingen. In productie wordt een ERP-export alleen gelezen als de connectorinstellingen van de eindklant hun eigen verkoper en betaling bevatten, niet het voorbeeld van de mapping: anders volgt 422 connector-settings-missing, met de naam van wat ontbreekt. Een sandbox leest hem met het voorbeeld, zoals eerder.
Een fout- of redencode opzoeken GET
Geeft het cataloguspunt voor een regel-ID, een foutcode van het verzendkanaal of een Franse redencode (ID's en aliassen).