E-facturatie-API: XRechnung, ZUGFeRD, Factur-X, Peppol BIS, FA(3)

KRONENWERK heeft geen afzonderlijk endpoint voor "e-factuurgeneratie". Gestructureerde e-facturen worden aangemaakt en gevalideerd op het moment dat een factuur in het product wordt uitgereikt, in het formaat dat het land van de verkoper vereist: XRechnung of ZUGFeRD in Duitsland, Factur-X in Frankrijk, Peppol BIS Billing 3.0 UBL in België, FA(3)-XML in Polen. Uw integratie maakt het concept aan met POST /invoices/drafts en ontvangt invoice.issued wanneer het gevalideerde document bestaat. Daarnaast valideert een gratis, anonieme controle op POST /api/v1/meta/pruefen elk bestand tegen de regels van een land en slaat niets op.

Hoe gestructureerde formaten uit een concept worden aangemaakt

Een concept bevat feiten: verkoper, koper, regels, datums, valuta. Wanneer een persoon het uitreikt, zet de landenmodule van de juridische entiteit van de verkoper die feiten om in het document dat dat land verwacht en valideert het resultaat voordat het factuurnummer wordt verbruikt. Dezelfde feiten leveren een pdf voor de lezer en een gestructureerd bestand voor de machine op; welke gestructureerde syntax en welk profiel hangen af van het land en van de instellingen van de onderneming.

1. Het fiscale oordeel wordt berekend uit de feiten (land van verkoper en koper, onderneming of consument, aard van de levering) en het btw-identificatienummer van de koper wordt via VIES gecontroleerd. Een oordeel "invoer vereist" blokkeert de uitreiking totdat een persoon beslist.
2. De landenmodule genereert het gestructureerde document — UBL, CII, PDF/A-3 met ingesloten CII, of FA(3)-XML.
3. Het document wordt gevalideerd met de regels die dat land publiceert. Een Duits document loopt door de KoSIT-Schematron-regels en wordt gekruist met de Mustang-bibliotheek; de validators die zijn uitgevoerd, worden samen met het resultaat vastgelegd.
4. Alleen als de validatie slaagt, wordt het nummer verbruikt, de archiefrij bevroren en invoice.issued in de wachtrij gezet voor uw webhook-endpoint.

Daarom stopt de API bij het concept. Een document dat niet door de validatie komt, is een document dat een persoon moet herstellen, en de velden die het formaat bepalen, zijn instellingen van de juridische entiteit, geen parameters van een verzoek. De redenering staat uitgewerkt op de pagina over de factuur-API.

Gedrag per land bij uitreiking

XRechnung, ZUGFeRD, Factur-X en Peppol BIS zijn allemaal implementaties van het Europese semantische model EN 16931; ZUGFeRD en Factur-X zijn technisch dezelfde hybride standaard, gezamenlijk gepubliceerd door FeRD en FNFE-MPE. FA(3) is het eigen schema van Polen en is geen EN 16931-syntax. De formaten worden vergeleken op e-factuurformaten; de Duitse keuze wordt toegelicht op XRechnung versus ZUGFeRD.

Wat de API over e-facturen blootstelt

Minder dan u misschien verwacht, en de lijst is exact.

• POST /invoices/drafts start het concept dat het gestructureerde document zal worden. Het aanvaardt alleen customerId.
• GET /invoices en GET /invoices/{number} geven de bevroren cijfers van de uitgereikte factuur terug: number, documentType, buyer, currency, issuedOn, dueOn, deliveredOn, net, tax, gross, outstanding, paymentState, overdue, cancelled, creditNote, paidOn, recordedAt.
• De webhook invoice.issued meldt dat er nu een gevalideerd document bestaat, met invoiceId, number, documentType, buyerName, issueDate, dueDate, currency, netMinor, taxMinor, grossMinor, amountDueMinor en paymentState.

Niet blootgesteld, en op geen enkele scope bereikbaar: het XML- of pdf-bestand zelf, het validatierapport van een uitgereikte factuur, de redenering achter het fiscale oordeel, de Peppol- of KSeF-verzendstatus, en elk endpoint dat uitreikt, verzendt of annuleert. De bestanden worden in het product gedownload; verzending wordt daar geconfigureerd en opgevolgd. Of een toekomstige versie van de API bestandsdownload toevoegt, wordt hier niet beloofd.

De gratis controle: POST /api/v1/meta/pruefen

De controle valideert één bestand tegen de regels van één land en antwoordt met een gestructureerd oordeel. Er is geen account en geen API-sleutel voor nodig, en ze bewaart niets — niet het bestand, geen digest, geen rij. Ze bestaat omdat elke Duitse onderneming sinds 1 januari 2025 gestructureerde e-facturen moet aanvaarden en de meeste geen manier hebben om te zien of de factuur die net is binnengekomen geldig is; geld vragen voor die controle zou geld vragen zijn voor compliance zelf. De browserversie staat op een e-factuur controleren.

Het verzoek is multipart/form-data met twee delen: datei (het bestand) en land (de ISO-landcode waarvan de regels gelden: DE, FR, BE, PL, CA of US). Het land is verplicht. Vroeger was Duitsland de standaardwaarde, en een Belgische factuur die tegen Duitse regels wordt gecontroleerd, krijgt een stellig antwoord dat stellig fout is.

curl -X POST https://kronenwerk.org/api/v1/meta/pruefen \
  -F "datei=@rechnung.xml" \
  -F "land=DE"

{
  "istERechnung": true,
  "lesbar": true,
  "gueltig": false,
  "format": "XRechnung (UBL)",
  "profil": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "zusammenfassung": "…",
  "lieferant": "Beispiel GmbH",
  "nummer": "2026-0041",
  "rechnungsdatum": "2026-08-28",
  "waehrung": "EUR",
  "nettoMinor": 89000,
  "steuerMinor": 16910,
  "bruttoMinor": 105910,
  "fehler": [
    { "schwere": "…", "quelle": "…", "regel": "BR-DE-15", "ort": "…", "meldung": "…" }
  ],
  "hinweise": [],
  "leseprobleme": [],
  "validatoren": ["KoSIT validationtool …", "…"]
}

De drie booleans beantwoorden drie verschillende vragen. istERechnung: is dit überhaupt een gestructureerde e-factuur, in tegenstelling tot een gewone pdf of een afbeelding. lesbar: kon het document als factuur worden ingelezen. gueltig: voldoet het aan de regels van het land. Een gewone pdf is istERechnung: false en geen fout. fehler en hinweise zijn lijsten van bevindingen, elk met een ernst, de validator die ze meldde, de regel-identificatie, een locatie en een bericht. leseprobleme somt extractieproblemen op, validatoren de validators die daadwerkelijk zijn uitgevoerd, zodat een gedeeltelijke controle als gedeeltelijk zichtbaar is. De totalen zijn alleen aanwezig als het document klopt; een document dat niet klopt, is al een bevinding, en geen totaal tonen is beter dan een gok tonen. De waarden van format, profil en zusammenfassung hangen af van het bestand en zijn hierboven illustratief.

Grenzen van de controle

• Bestanden groter dan 25 MB worden geweigerd met 413 voordat er één byte wordt geparseerd. Een echte e-factuur met haar ingesloten XML is enkele honderden kilobytes groot.
• Verzoeken zijn beperkt per clientadres: een budget van 5 controles dat met één controle per 60 seconden wordt aangevuld. Daarboven is het antwoord 429 met een Retry-After-header en een JSON-body die zegt hoelang u moet wachten. De controle is een hulpmiddel voor mensen en incidentele scripts, geen dienst voor bulkvalidatie.
• Er wordt niets opgeslagen, dus er is geen geschiedenis en geen link om naar terug te keren. Bewaar het antwoord als u het nodig hebt.
• De controle valideert; ze beslist geen juridische vragen. Of een document dat slaagt in uw situatie ook een correcte factuur voor btw-doeleinden is, vereist professionele bevestiging.

Gestructureerde facturen ontvangen

Dezelfde lezers achter de controle worden binnen het product gebruikt: inkomende XRechnung-, ZUGFeRD/Factur-X- en UBL-documenten worden ingelezen als inkoopfacturen met hun leverancier, nummer, datum en totalen, en hun validatieresultaat wordt bij de inkoopfactuur opgeslagen. Dat inkomende pad is vandaag niet op de publieke API blootgesteld; inkoopfacturen die in het product zijn geregistreerd, worden naar buiten gemeld door de webhook purchase.recorded met purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor en grossMinor. De Duitse ontvangstplichten worden toegelicht op e-facturen ontvangen in Duitsland.

Hoe KRONENWERK dit afhandelt

ONDERSTEUND MET BEPERKINGEN Generatie en validatie van XRechnung, ZUGFeRD, Factur-X, Peppol BIS UBL en FA(3) bij uitreiking maken deel uit van het product (e-facturatie). Het aandeel van de API daarin is het concept, het teruglezen en de webhook, op het Enterprise-plan (prijzen). De controle is gratis voor iedereen. Transport is waar de beperkingen zitten: verzenden en ontvangen via Peppol verlopen via een geaccrediteerde toegangspuntaanbieder (Storecove) zodra de onderneming is verbonden in Instellingen → Verzending — KRONENWERK is zelf geen Peppol Access Point; Franse verzending via een plateforme agréée is gepland via de functie voor goedgekeurde platforms van Storecove en is nog niet productieklaar; de Poolse KSeF 2.0-module is niet gebruikt tegen de productie-KSeF. Elk daarvan komt op een eigen pagina aan bod: Peppol-integratie, KSeF-integratie, en de formaatgids voor ontwikkelaars op EN 16931 voor ontwikkelaars.