Podanie hotového dokumentu UBL alebo CII (priame odovzdanie)
- V sandboxe
Jednoducho povedané
Pre ERP, ktoré už zapisujú UBL alebo CII, alebo FA(3) pre kanál KSeF. Nič sa nemapuje: služba spustí
oficiálne validátory kanála (pre FA(3): XSD plus pravidlá súboru a dátumu KSeF) a odošle
súbor nezmenený. PDF Factur-X alebo ZUGFeRD prejde tým istým koncovým bodom
ako application/pdf. XML sa číta s vypnutými entitami, DTD a prístupom do siete, a súbor s
DOCTYPE sa odmietne (EI-XML-DTD) skôr, než ho prečíta ktorýkoľvek validátor, rovnako ako súbor, ktorý nie je správne utvorený
(EI-XML-SYNTAX) alebo nie je faktúrou, ktorú kanál pozná (EI-XML-TYPE). Od 0.18.4 je ten istý súbor poslaný znova
pre klienta a kanál už držanou faktúrou (duplicate_of), ako pri POST /invoices; nič nové sa neodošle.
apiKeyAuthorizationBearer <token>Kľúč posielajte ako token typu Bearer: Authorization: Bearer <your-api-key>. Stav služby je jediné volanie, ktoré nevyžaduje kľúč.
route*stringKanál krajiny. Rovnaké hodnoty ako country_route v stavových udalostiach.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringVlastné ID dokladu v ERP.
length <= 100Idempotency-Key*stringJedinečný kľúč pre každú logickú požiadavku (postačí UUID). Uchováva sa tak dlho, ako sa uchovávajú údaje klienta. S kľúčom operátora nesmie začínať na client: (400), v takom tvare sa ukladajú kľúče klientov.
8 <= length <= 100body*stringPrijaté na spracovanie.
application/json- response
id*stringstate*InvoiceStateVlastný stav služby pre faktúru. Stavové udalosti hlásia životný cyklus viditeľný pre partnera;
queued a submitting sú vnútorné kroky medzi validated a submitted. validation_failed znamená, že oficiálne pravidlá dokument odmietli; od
0.18.4 sa kontrola, ktorá sa nespustila (KOSIT-RUN, EI-PDF-CHECK), opakuje a potom skončí ako dead_letter s týmto
kódom. dead_letter drží svoj dokument, takže ten istý súbor odpovie s duplicate_of; od 0.18.6 môže
operátor zrušiť faktúru, pre ktorú sa neuskutočnilo žiadne volanie kanála, a potom môže súbor ísť znova.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Nastavené, keď sa ten istý dokument pre tohto klienta a kanál už prijal; nič nové sa neodošle. Podanie, ktoré skončilo ako rejected, validation_failed alebo cancelled, sa nepočíta, takže súbor možno poslať znova. Od 0.18.5 to platí aj pre dve požiadavky poslané v tom istom okamihu pod rôznymi kľúčmi; jedna faktúru vytvorí a druhá odpovie s duplicate_of.
links*route?RouteLen keď kanál vybral smerovač.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Len keď požiadavka kanál vynechala.
"router"route_rule?stringPravidlo smerovača, ktoré kanál vybralo; zapisuje sa aj do auditného záznamu ako 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"}Podanie faktúry alebo dobropisu ako kanonického JSON POST
Služba hneď skontroluje dokument voči kanonickému modelu a predbežným kontrolám a pri zlyhaní ktorejkoľvek odpovie 422. Všetko ďalšie prebieha asynchrónne (zostavenie, oficiálna validácia, podanie na kanál, stavy) a oznamuje sa stavovými udalosťami. Opravené opätovné podanie odmietnutej faktúry používa rovnaký invoice_ref a nový Idempotency-Key; služba pokusy prepojí. V produkcii sa export z ERP prečíta len vtedy, keď nastavenia konektora klienta obsahujú vlastného predávajúceho a platbu, nie príklad z mapovania: inak odpovie 422 connector-settings-missing s uvedením, čo chýba. Sandbox ho číta s príkladom, ako predtým.
Vyhľadanie kódu chyby alebo dôvodu GET
Vráti položku katalógu pre ID pravidla, kód chyby kanála alebo francúzsky kód dôvodu (ID a aliasy).