Eine Rechnung oder Gutschrift als kanonisches JSON übermitteln
- In der Sandbox
In einfachen Worten
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.
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.
Idempotency-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 <= 100application/json- body
Senden Sie entweder document (eine kanonische Rechnung) oder connector mit export (ein ERP-Dokument, wie das ERP es
zurückgibt), nicht beides (400). Ein Export wird mit der aktiven Mapping-Version des Connectors oder mit mapping_version gemappt und
danach genau so behandelt wie die kanonische Rechnung, auf die er abgebildet wird; der Export selbst wird mit der Rechnung aufbewahrt
(erp-export). Das XRechnung-Profil des Connectors gilt nur auf DE-XRECHNUNG und dann, wenn der Router für
einen deutschen Käufer wählt. Ein Mapping-Befund (eine unbekannte Einheit, ein fehlendes ERP-Feld) wird mit 422 und dem ERP-Feld beantwortet.
connector?connectorAus welchem ERP der Export stammt. business-central: eine Verkaufsrechnung der Business Central API v2.0. Ein anderes SAP-Objekt, etwa ein Auftrag oder ein Entwurf, wird mit 400 beantwortet.
"business-central""sap-b1"export?Das ERP-Dokument, wie das ERP es zurückgibt. Felder, die das Mapping nicht liest, werden ignoriert.
mapping_version?mapping_versionEine Mapping-Version dieses Connectors. Die aktive, wenn weggelassen; eine unbekannte wird mit 400 beantwortet.
^v[0-9]+$client?stringDer Kunde, zu dem die Rechnung gehört. Der Schlüssel des Betreibers nennt ihn (weggelassen, gehört die Rechnung zum eigenen Kunden local des Betreibers). Ein Kundenschlüssel darf ihn weglassen oder seinen eigenen Kunden nennen; jeder andere Kunde wird mit 403 beantwortet.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringDie eigene Dokument-ID des ERP. Wird in jedem Statusereignis zurückgegeben.
length <= 100route?|Weggelassen oder null, wählt der Router ihn aus dem Dokument: dem country des Verkäufers,
dem buyer.address.country des Käufers, dem profile, den gespeicherten Zugangsdaten des Kunden und, wenn eine Regel
es braucht, der Peppol-Registrierung des Käufers. Passt keine Regel, lautet die Antwort 422 mit EI-ROUTE-UNDECIDED oder
EI-ROUTE-PEPPOL-UNKNOWN (Quelle router). POST /validate braucht ihn weiterhin.
environment?stringMuss zur Umgebung des API-Schlüssels passen; wird ausdrücklich als Absicherung angegeben.
"sandbox""production"document*Eine Rechnung im kanonischen Modell. Die Bedeutung der Felder folgt dem semantischen Modell von EN 16931. Summen sind nicht Teil des Modells: Der Service berechnet sie aus den Positionen.
formats?array<>Welche Dokumente erzeugt werden, wo der Übermittlungsweg eine Wahl lässt (Deutschland: xrechnung-ubl,
xrechnung-cii oder zugferd; Frankreich: ubl, cii oder facturx). Die Standardwerte je Übermittlungsweg werden beim Onboarding festgelegt.
Bei POST /invoices nennen Sie höchstens eines: Es ist das Dokument, das erstellt, geprüft und gesendet wird (das erste in jeder
obigen Liste, wenn weggelassen). Peppol und Rumänien nehmen ubl, Polen fa3. Ein anderer Wert oder mehr als einer
wird mit 400 beantwortet. Factur-X und ZUGFeRD werden zweimal geprüft: das darin enthaltene CII mit den Regeln des Übermittlungswegs, dann das PDF.
Auf dem deutschen Übermittlungsweg wird ein Dokument ohne profile als XRechnung erstellt.
erp_totals?Die Summen, die das ERP berechnet hat. Der Service berechnet seine eigenen aus den Zeilen und lehnt die Rechnung ab (422, EI-TOTALS-MISMATCH, mit dem ERP-Feld), wenn sie abweichen, statt ein Dokument zu senden, dem das ERP widersprechen würde. Ein Connector liest diese aus dem Export selbst; hier genannte Summen haben Vorrang.
Zur Verarbeitung angenommen. Verfolgen Sie sie mit den zurückgegebenen Links oder warten Sie auf Statusereignisse.
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" \ -H "Authorization: Bearer <your-api-key>" \ -H "Idempotency-Key: order-2026-0001" \ -H "Content-Type: application/json" \ -d '{ "invoice_ref": "CAPTURE-JSON-1790961440", "route": "DE-XRECHNUNG", "environment": "sandbox", "document": { "lang": "de", "country": "DE", "invoice": { "number": "DOC-mux3dlqm", "issue_date": "2026-09-26", "due_date": "2026-10-10", "type_code": 380, "currency": "EUR", "buyer_reference": "PO-88731", "period": { "start": "2026-09-01", "end": "2026-09-30" }, "notes": [ "Vielen Dank für Ihren Auftrag." ] }, "seller": { "name": "Nordlicht Software GmbH", "address": { "street": "Hafenstraße 12", "city": "Hamburg", "postcode": "20457", "country": "DE" }, "vat_id": "DE938296582", "tax_number": "27/123/45678", "company_id": "HRB 123456", "register": "Amtsgericht Hamburg HRB 123456", "managing_directors": "Geschäftsführer: Jana Petersen", "legal_info": "GmbH", "endpoint": { "id": "DE938296582", "scheme": "9930" }, "contact": { "name": "Jana Petersen", "email": "[email protected]", "phone": "+49 40 1234567" }, "brand_color": "#1160FF", "accent_color": "#FF9021" }, "buyer": { "name": "Brauhaus Weber AG", "address": { "street": "Marienplatz 4", "city": "München", "postcode": "80331", "country": "DE" }, "vat_id": "DE965003781", "endpoint": { "id": "DE965003781", "scheme": "9930" } }, "lines": [ { "name": "E-Rechnung Einführung (Festpreis)", "description": "Mapping Business Central → EN 16931, Validierung XRechnung, Test im Peppol-Testnetz", "quantity": 1, "unit": "LS", "unit_price": 5900, "vat_category": "S", "vat_rate": 19 }, { "name": "Betreuung abgelehnter Rechnungen", "description": "Care Plus, September 2026", "quantity": 1, "unit": "MON", "unit_price": 349, "vat_category": "S", "vat_rate": 19 }, { "name": "Zusätzliche Schulung", "description": "Remote, Buchhaltungsteam", "quantity": 3, "unit": "HUR", "unit_price": 120, "vat_category": "S", "vat_rate": 19 } ], "payment": { "means_code": 58, "iban": "DE89 3704 0044 0532 0130 00", "bic": "COBADEFFXXX", "reference": "RE-2026-0143", "terms": "Zahlbar innerhalb von 14 Tagen ohne Abzug." }, "profile": "xrechnung" } }'{ "links": { "self": "/invoices/inv_936a93e38de84e7b0a1d7681", "events": "/invoices/inv_936a93e38de84e7b0a1d7681/events" }, "id": "inv_936a93e38de84e7b0a1d7681", "state": "queued"}Rechnungen auflisten und suchen GET
Ein Kundenschlüssel sieht die Rechnungen seines eigenen Kunden; der Betreiber sieht die aller Kunden, oder mit client die eines Kunden. Die Zeilen enthalten, was GET /invoices/{id} enthält, ohne documents, und keinen Rechnungsinhalt: weder Käufer noch Beträge und kein Ausstellungsdatum (für Rumänien und Polen folgt daraus deadline_at, auf wenige Tage genau). Ein unbekannter Parameter wird mit 400 beantwortet.
Ein fertiges UBL- oder CII-Dokument übermitteln (Durchreichen) POST
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.