Transmiteți un document UBL sau CII finalizat (transmitere directă)
- În sandbox
În cuvinte simple
Pentru ERP-urile care scriu deja UBL sau CII, sau FA(3) pentru canalul KSeF. Nu are loc nicio mapare: serviciul rulează
validatoarele oficiale ale canalului (pentru FA(3): XSD plus regulile KSeF pentru fișier și dată) și trimite
fișierul neschimbat. Un PDF Factur-X sau ZUGFeRD trece prin același punct final
ca application/pdf. XML-ul este analizat cu entitățile, DTD-urile și accesul la rețea dezactivate, iar un fișier cu
DOCTYPE este refuzat (EI-XML-DTD) înainte ca vreun validator să îl citească, la fel ca un fișier care nu este bine format
(EI-XML-SYNTAX) sau nu este o factură pe care canalul o cunoaște (EI-XML-TYPE). Începând cu 0.18.4, același fișier trimis din nou
pentru același client și canal este factura deja păstrată (duplicate_of), ca la POST /invoices; nu se trimite nimic nou.
apiKeyAuthorizationBearer <token>Trimiteți cheia ca token de tip bearer: Authorization: Bearer <your-api-key>. Starea serviciului este singurul apel care nu necesită cheie.
route*stringCanalul de transmitere. Aceleași valori ca country_route din evenimentele de stare.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringID-ul propriu al documentului în ERP.
length <= 100Idempotency-Key*stringO cheie unică pentru fiecare cerere logică (un UUID este suficient). Se păstrează cât timp se păstrează datele clientului. Cu cheia operatorului nu poate începe cu client: (400), forma sub care sunt stocate cheile clienților.
8 <= length <= 100body*stringAcceptată pentru procesare.
application/json- response
id*stringstate*InvoiceStateStarea proprie a serviciului pentru o factură. Evenimentele de stare raportează ciclul de viață vizibil partenerului;
queued și submitting sunt pași interni între validated și submitted. validation_failed înseamnă că regulile oficiale au refuzat documentul; începând cu
0.18.4, o verificare care nu a rulat (KOSIT-RUN, EI-PDF-CHECK) se reîncearcă, apoi se încheie ca dead_letter cu acel
cod. Un dead_letter își păstrează documentul reținut, deci același fișier primește răspuns cu duplicate_of; începând cu 0.18.6, operatorul
poate anula una pentru care nu s-a făcut niciun apel către canal, iar apoi fișierul poate fi trimis din nou.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Setat când același document a fost deja acceptat pentru acest client și canal; nu se trimite nimic nou. O transmitere care s-a încheiat ca rejected, validation_failed sau cancelled nu contează, deci fișierul poate fi trimis din nou. Începând cu 0.18.5 acest lucru este valabil și pentru două cereri trimise în același moment, sub chei diferite; una creează factura, iar cealaltă răspunde cu duplicate_of.
links*route?RouteDoar când routerul a ales canalul.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Doar când cererea a omis canalul.
"router"route_rule?stringRegula routerului care a ales canalul; scrisă și în jurnalul de audit ca 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"}Transmiteți o factură sau o notă de credit ca JSON canonic POST
Serviciul verifică imediat documentul față de modelul canonic și verificările preliminare și răspunde cu 422 dacă oricare eșuează. Tot ce urmează rulează asincron (generare, validare oficială, transmiterea pe canal, stări) și este raportat prin evenimente de stare. O retransmitere corectată a unei facturi respinse folosește același invoice_ref și un Idempotency-Key nou; serviciul leagă încercările. În producție, un export ERP este citit doar când setările conectorului clientului conțin propriul vânzător și propria plată, nu exemplul din mapare: altfel 422 connector-settings-missing, cu indicarea a ceea ce lipsește. Un sandbox îl citește cu exemplul, ca până acum.
Căutați un cod de eroare sau de motiv GET
Returnează intrarea din catalog pentru un ID de regulă, un cod de eroare al canalului sau un cod de motiv francez (ID-uri și alias-uri).