Een factuur of creditnota als canonieke JSON indienen
- In de sandbox
In gewone woorden
De dienst controleert het document tegelijk tegen het canonieke model en de voorafgaande controles, en antwoordt 422 als een van beide faalt. Alles daarna verloopt asynchroon (opbouw, officiële validatie, verzending naar het verzendkanaal, statussen) en wordt gemeld via statusberichten.
Een gecorrigeerde nieuwe indiening van een afgewezen factuur gebruikt dezelfde invoice_ref en een nieuwe
Idempotency-Key; de dienst koppelt de pogingen.
In productie wordt een ERP-export alleen gelezen als de connectorinstellingen van de eindklant hun eigen verkoper en betaling bevatten,
niet het voorbeeld van de mapping: anders volgt 422 connector-settings-missing, met de naam van wat ontbreekt. Een sandbox leest hem
met het voorbeeld, zoals eerder.
apiKeyAuthorizationBearer <token>Stuur uw sleutel als bearer-token: Authorization: Bearer <your-api-key>. De health-aanroep is de enige aanroep die geen sleutel vereist.
Idempotency-Key*stringEen unieke sleutel per logisch verzoek (een UUID is prima). Wordt bewaard zolang de gegevens van de eindklant worden bewaard. Met de sleutel van de beheerder mag hij niet beginnen met client: (400), de vorm waaronder sleutels van eindklanten worden bewaard.
8 <= length <= 100application/json- body
Stuur document (een canonieke factuur) of connector met export (één ERP-document zoals het ERP het teruggeeft),
niet beide (400). Een export wordt gemapt met de geldige mappingversie van de connector, of mapping_version, en
daarna precies behandeld als de canonieke factuur waarop hij wordt gemapt; de export zelf wordt bij de factuur bewaard
(erp-export). Het XRechnung-profiel van de connector geldt alleen op DE-XRECHNUNG, en als de router kiest voor
een Duitse koper. Een bevinding van de mapping (een onbekende eenheid, een ontbrekend ERP-veld) geeft 422 met de naam van het ERP-veld.
connector?connectorUit welk ERP de export komt. business-central: één verkoopfactuur van Business Central API v2.0. Een ander SAP-object, zoals een order of een concept, geeft 400.
"business-central""sap-b1"export?Het ERP-document zoals het ERP het teruggeeft. Velden die de mapping niet leest, worden genegeerd.
mapping_version?mapping_versionEen mappingversie van die connector. De geldige als u niets noemt; een onbekende geeft 400.
^v[0-9]+$client?stringDe eindklant van wie de factuur is. De sleutel van de beheerder noemt hem (weggelaten hoort de factuur bij de eigen eindklant local van de beheerder). Een sleutel van een eindklant mag hem weglaten of de eigen eindklant noemen; elke andere eindklant geeft 403.
^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$invoice_ref?stringDe eigen document-ID van het ERP. Wordt in elk statusbericht herhaald.
length <= 100route?|Weggelaten of null kiest de router het uit het document: het country van de
verkoper, het buyer.address.country van de koper, profile, de bewaarde toegangsgegevens van de eindklant en, als een regel
het nodig heeft, de Peppol-registratie van de koper. Als geen regel past, is het antwoord 422 met EI-ROUTE-UNDECIDED of
EI-ROUTE-PEPPOL-UNKNOWN (bron router). POST /validate heeft het nog steeds nodig.
environment?stringMoet overeenkomen met de omgeving van de API-sleutel; expliciet opgegeven als controle.
"sandbox""production"document*Eén factuur in het canonieke model. De betekenis van de velden volgt het semantische model van EN 16931. Totalen maken geen deel uit van het model: de dienst berekent ze uit de factuurregels.
formats?array<>Welke documenten worden gemaakt waar het verzendkanaal een keuze toelaat (Duitsland: xrechnung-ubl,
xrechnung-cii of zugferd; Frankrijk: ubl, cii of facturx). De standaarden per verzendkanaal worden bij de onboarding vastgelegd.
Noem bij POST /invoices er hoogstens een: dat is het document dat wordt opgebouwd, gecontroleerd en verzonden (het eerste in elke
lijst hierboven als u niets noemt). Peppol en Roemenië nemen ubl, Polen fa3. Een andere waarde, of meer dan een,
geeft 400. Factur-X en ZUGFeRD worden tweemaal gecontroleerd: de CII erin met de regels van het verzendkanaal, daarna de PDF.
Op het Duitse verzendkanaal wordt een document zonder profile opgebouwd als XRechnung.
erp_totals?De totalen die het ERP heeft berekend. De dienst berekent zijn eigen totalen uit de regels en weigert de factuur (422, EI-TOTALS-MISMATCH, met de naam van het ERP-veld) als ze verschillen, in plaats van een document te verzenden waarmee het ERP het oneens is. Een connector leest ze uit de export zelf; hier genoemde totalen gaan voor.
Geaccepteerd voor verwerking. Volg de factuur via de teruggegeven links of wacht op statusberichten.
application/json- response
id*stringstate*InvoiceStateDe eigen status van de dienst voor een factuur. Statusberichten melden de levenscyclus zoals de partner hem ziet;
queued en submitting zijn interne stappen tussen validated en submitted. validation_failed betekent dat de officiële regels het document hebben geweigerd; sinds
0.18.4 wordt een controle die niet draaide (KOSIT-RUN, EI-PDF-CHECK) opnieuw geprobeerd en eindigt dan als dead_letter met die
code. Een dead_letter houdt zijn document vast, zodat hetzelfde bestand antwoordt met duplicate_of; sinds 0.18.6 kan de
beheerder er een annuleren waarvoor geen aanroep naar het verzendkanaal is gedaan, en dan kan het bestand opnieuw worden verzonden.
"received""source_error""validated""validation_failed""queued""submitting""submitted""ready""accepted""rejected""delivered""cancelled""dead_letter"duplicate_of?|Gezet als hetzelfde document al was geaccepteerd voor deze eindklant en dit verzendkanaal; er wordt niets nieuws verzonden. Een indiening die eindigde als rejected, validation_failed of cancelled telt niet mee, zodat het bestand opnieuw kan worden verzonden. Sinds 0.18.5 geldt dit ook voor twee verzoeken die op hetzelfde moment worden verzonden, onder verschillende sleutels; een maakt de factuur aan en de ander antwoordt met duplicate_of.
links*route?RouteAlleen als de router het verzendkanaal koos.
"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"route_chosen_by?"router"Alleen als het verzoek het verzendkanaal wegliet.
"router"route_rule?stringDe regel van de router die het verzendkanaal koos; ook in het auditlogboek geschreven als 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" \ -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": "rechnung@nordlicht.example", "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"}Facturen tonen en zoeken GET
Een sleutel van een eindklant ziet de facturen van die eindklant; de beheerder ziet die van alle eindklanten, of van één eindklant met client. De rijen bevatten wat GET /invoices/{id} bevat, zonder documents, en geen factuurinhoud: geen koper of bedragen, en geen uitgiftedatum (voor Roemenië en Polen volgt de deadline_at daaruit, tot op enkele dagen nauwkeurig). Een onbekende parameter geeft 400.
Een afgewerkt UBL- of CII-document indienen (doorgifte) POST
Voor ERP's die al UBL of CII schrijven, of FA(3) voor het KSeF-verzendkanaal. Er vindt geen mapping plaats: de dienst voert de officiële validators voor het verzendkanaal uit (voor FA(3): de XSD plus de bestands- en datumregels van KSeF) en verzendt het bestand ongewijzigd. Een Factur-X- of ZUGFeRD-PDF gaat via hetzelfde eindpunt als application/pdf. De XML wordt gelezen met entiteiten, DTD's en netwerktoegang uitgeschakeld, en een bestand met een DOCTYPE wordt geweigerd (EI-XML-DTD) voordat een validator het leest, net als een bestand dat niet welgevormd is (EI-XML-SYNTAX) of geen factuur is die het verzendkanaal kent (EI-XML-TYPE). Sinds 0.18.4 is hetzelfde bestand dat opnieuw wordt verzonden voor de eindklant en het verzendkanaal de factuur die al is bewaard (duplicate_of), zoals bij POST /invoices; er wordt niets nieuws verzonden.