Ein fertiges UBL- oder CII-Dokument übermitteln (Durchreichen)
- In der Sandbox
In einfachen Worten
Für ERPs, die bereits UBL oder CII schreiben, oder FA(3) für den Übermittlungsweg KSeF. Es findet kein Mapping statt: Der Service führt
die offiziellen Validatoren des Übermittlungswegs aus (für FA(3): das XSD plus die Datei- und Datumsregeln von KSeF) und sendet die
Datei unverändert. Ein Factur-X- oder ZUGFeRD-PDF läuft über denselben Endpunkt
als application/pdf. Das XML wird mit ausgeschalteten Entities, DTDs und Netzwerkzugriff geparst; eine Datei mit einem
DOCTYPE wird abgelehnt (EI-XML-DTD), bevor ein Validator sie liest, ebenso eine Datei, die nicht wohlgeformt ist
(EI-XML-SYNTAX) oder keine Rechnung ist, die der Übermittlungsweg kennt (EI-XML-TYPE). Seit 0.18.4 ist dieselbe Datei, die für
den Kunden und den Übermittlungsweg erneut gesendet wird, die bereits vorhandene Rechnung (duplicate_of), wie bei POST /invoices; es wird nichts Neues gesendet.
apiKeyAuthorizationBearer <token>Senden Sie Ihren Schlüssel als Bearer-Token: Authorization: Bearer <your-api-key>. Der Systemzustand ist der einzige Aufruf, der keinen Schlüssel braucht.
route*stringDer Übermittlungsweg. Dieselben Werte wie country_route in Statusereignissen.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"invoice_ref*stringDie eigene Beleg-ID des ERP.
length <= 100Idempotency-Key*stringEin eindeutiger Schlüssel je logischer Anfrage (eine UUID genügt). Er wird so lange aufbewahrt, wie die Daten des Kunden aufbewahrt werden. Mit dem Schlüssel des Betreibers darf er nicht mit client: beginnen (400), der Form, unter der Kundenschlüssel gespeichert werden.
8 <= length <= 100body*stringZur Verarbeitung angenommen.
application/json- response
id*stringstate*InvoiceStateDer eigene Zustand des Service für eine Rechnung. Statusereignisse melden den Lebenszyklus aus Sicht des Partners;
queued und submitting sind interne Schritte zwischen validated und submitted. validation_failed bedeutet, dass die offiziellen Regeln das Dokument abgelehnt haben; seit
0.18.4 wird eine Prüfung, die nicht lief (KOSIT-RUN, EI-PDF-CHECK), wiederholt und endet dann als dead_letter mit diesem
Code. Eine dead_letter hält ihr Dokument fest, sodass dieselbe Datei mit duplicate_of beantwortet wird; seit 0.18.6 kann der
Betreiber eine stornieren, für die kein Aufruf an den Übermittlungsweg gemacht wurde, und die Datei kann dann erneut gesendet werden.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Gesetzt, wenn dasselbe Dokument für diesen Kunden und Übermittlungsweg bereits angenommen wurde; es wird nichts Neues gesendet. Eine Übermittlung, die als rejected, validation_failed oder cancelled endete, zählt nicht, sodass die Datei erneut gesendet werden kann. Seit 0.18.5 gilt das auch für zwei Anfragen, die im selben Moment unter verschiedenen Schlüsseln gesendet werden; eine erzeugt die Rechnung, die andere antwortet mit duplicate_of.
links*route?RouteNur, wenn der Router den Übermittlungsweg gewählt hat.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Nur, wenn die Anfrage den Übermittlungsweg weggelassen hat.
"router"route_rule?stringDie Regel des Routers, die den Übermittlungsweg gewählt hat; wird auch als route_chosen ins Audit-Protokoll geschrieben.
"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>faktury@wisla.example</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"}Eine Rechnung oder Gutschrift als kanonisches JSON übermitteln POST
Der Service prüft das Dokument sofort gegen das kanonische Modell und die Vorprüfungen und antwortet mit 422, wenn eine davon fehlschlägt. Alles danach läuft asynchron (Erstellung, offizielle Validierung, Übermittlung an den Übermittlungsweg, Status) und wird über Statusereignisse gemeldet. Eine korrigierte erneute Übermittlung einer abgelehnten Rechnung verwendet dieselbe invoice_ref und einen neuen Idempotency-Key; der Service verknüpft die Versuche. In der Produktion wird ein ERP-Export nur gelesen, wenn die Connector-Einstellungen des Kunden seinen eigenen Verkäufer und seine eigene Zahlung enthalten, nicht das Beispiel des Mappings: sonst 422 connector-settings-missing, mit dem, was fehlt. Eine Sandbox liest ihn wie bisher mit dem Beispiel.
Einen Fehler- oder Grundcode nachschlagen GET
Gibt den Katalogeintrag für eine Regel-ID, einen Fehlercode des Übermittlungswegs oder einen französischen Grundcode zurück (IDs und Aliase).