Przesłanie gotowego dokumentu UBL lub CII (przekazanie bez zmian)
- W sandboxie
Prostymi słowami
Dla ERP, które już zapisują UBL lub CII albo FA(3) dla kanału KSeF. Nie ma mapowania: usługa uruchamia
oficjalne walidatory kanału (dla FA(3): XSD oraz reguły KSeF dotyczące pliku i dat) i wysyła
plik bez zmian. PDF Factur-X lub ZUGFeRD trafia przez ten sam punkt końcowy
jako application/pdf. XML jest parsowany z wyłączonymi encjami, DTD i dostępem do sieci, a plik z
DOCTYPE jest odrzucany (EI-XML-DTD), zanim odczyta go jakikolwiek walidator, tak samo jak plik, który nie jest poprawnie sformułowany
(EI-XML-SYNTAX) lub nie jest fakturą znaną kanałowi (EI-XML-TYPE). Od 0.18.4 ten sam plik wysłany ponownie
dla tego samego klienta i kanału to faktura już przechowywana (duplicate_of), jak w POST /invoices; nic nowego nie jest wysyłane.
apiKeyAuthorizationBearer <token>Klucz należy wysyłać jako token typu bearer: Authorization: Bearer <your-api-key>. Wywołanie stanu usługi jest jedynym, które nie wymaga klucza.
route*stringKrajowy kanał przesyłania. Te same wartości co country_route w zdarzeniach statusu.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringWłasny identyfikator dokumentu w ERP.
length <= 100Idempotency-Key*stringUnikalny klucz dla każdego logicznego żądania (może to być UUID). Przechowywany tak długo, jak dane klienta. Klucz operatora nie może zaczynać się od client: (400), czyli od postaci, pod którą zapisywane są klucze klientów.
8 <= length <= 100body*stringPrzyjęte do przetworzenia.
application/json- response
id*stringstate*InvoiceStateWłasny stan usługi dla faktury. Zdarzenia statusu zgłaszają cykl życia widoczny dla partnera;
queued i submitting to kroki wewnętrzne między validated a submitted. validation_failed oznacza, że oficjalne reguły odrzuciły dokument; od
0.18.4 kontrola, która się nie uruchomiła (KOSIT-RUN, EI-PDF-CHECK), jest ponawiana, a potem kończy jako dead_letter z tym
kodem. dead_letter zatrzymuje swój dokument, więc ten sam plik dostaje odpowiedź z duplicate_of; od 0.18.6
operator może anulować taką fakturę, dla której nie wykonano wywołania do kanału, i wtedy plik może zostać wysłany ponownie.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Ustawione, gdy ten sam dokument został już przyjęty dla tego klienta i kanału; nic nowego nie jest wysyłane. Przesłanie, które zakończyło się jako rejected, validation_failed lub cancelled, nie liczy się, więc plik można wysłać ponownie. Od 0.18.5 dotyczy to także dwóch żądań wysłanych w tej samej chwili pod różnymi kluczami; jedno tworzy fakturę, a drugie odpowiada z duplicate_of.
links*route?RouteTylko gdy kanał wybrał router.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Tylko gdy żądanie pomijało kanał.
"router"route_rule?stringReguła routera, która wybrała kanał; zapisywana także w dzienniku audytu jako 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"}Przesłanie faktury lub noty kredytowej jako kanonicznego JSON POST
Usługa od razu sprawdza dokument z modelem kanonicznym i kontrolami wstępnymi i odpowiada 422, jeśli któraś z nich się nie powiedzie. Wszystko, co dzieje się potem, przebiega asynchronicznie (budowanie, oficjalna walidacja, przesłanie do kanału, statusy) i jest zgłaszane zdarzeniami statusu. Poprawione ponowne przesłanie odrzuconej faktury używa tego samego invoice_ref i nowego Idempotency-Key; usługa łączy te próby. Na produkcji eksport z ERP jest odczytywany tylko wtedy, gdy ustawienia konektora klienta zawierają jego własnego sprzedawcę i płatność, a nie przykład z mapowania: w przeciwnym razie 422 connector-settings-missing ze wskazaniem, czego brakuje. Sandbox odczytuje go z przykładem, jak dotąd.
Wyszukanie kodu błędu lub przyczyny GET
Zwraca wpis katalogu dla identyfikatora reguły, kodu błędu kanału lub francuskiego kodu przyczyny (identyfikatory i aliasy).