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

KRONENWERK hat keinen separaten Endpunkt zur „E-Rechnungserzeugung“. Strukturierte E-Rechnungen werden in dem Moment erzeugt und validiert, in dem eine Rechnung im Produkt ausgestellt wird, und zwar in dem Format, das das Land des Verkäufers verlangt: XRechnung oder ZUGFeRD in Deutschland, Factur-X in Frankreich, Peppol BIS Billing 3.0 UBL in Belgien, FA(3)-XML in Polen. Ihre Integration legt den Entwurf mit POST /invoices/drafts an und erhält invoice.issued, sobald das validierte Dokument existiert. Davon getrennt validiert ein kostenloser, anonymer Prüfer unter POST /api/v1/meta/pruefen jede Datei gegen die Regeln eines Landes und speichert nichts.

Wie strukturierte Formate aus einem Entwurf entstehen

Ein Entwurf enthält Fakten: Verkäufer, Käufer, Positionen, Daten, Währung. Wenn eine Person ihn ausstellt, verwandelt das Ländermodul der rechtlichen Einheit des Verkäufers diese Fakten in das Dokument, das dieses Land erwartet, und validiert das Ergebnis, bevor die Rechnungsnummer verbraucht wird. Dieselben Fakten erzeugen ein PDF für den Leser und eine strukturierte Datei für die Maschine; welche strukturierte Syntax und welches Profil verwendet wird, hängt vom Land und von den Einstellungen des Unternehmens ab.

1. Das Steuerergebnis wird aus den Fakten berechnet (Land von Verkäufer und Käufer, Unternehmen oder Verbraucher, Art der Leistung), und die USt-IdNr. des Käufers wird gegen VIES geprüft. Ein Ergebnis „Eingabe erforderlich“ hält die Ausstellung an, bis eine Person entscheidet.
2. Das Ländermodul rendert das strukturierte Dokument — UBL, CII, PDF/A-3 mit eingebettetem CII oder FA(3)-XML.
3. Das Dokument wird mit den Regeln validiert, die das jeweilige Land veröffentlicht. Ein deutsches Dokument durchläuft die KoSIT-Schematron-Regeln und wird mit der Mustang-Bibliothek gegengeprüft; die gelaufenen Validatoren werden mit dem Ergebnis festgehalten.
4. Nur wenn die Validierung besteht, wird die Nummer verbraucht, die Archivzeile eingefroren und invoice.issued für Ihren Webhook-Endpunkt in die Warteschlange gestellt.

Deshalb endet die API beim Entwurf. Ein Dokument, das die Validierung nicht besteht, ist ein Dokument, das eine Person korrigieren muss, und die Felder, die über das Format entscheiden, sind Einstellungen der rechtlichen Einheit, keine Parameter einer Anfrage. Die Begründung ist auf der Seite zur Rechnungs-API dargelegt.

Verhalten je Land bei der Ausstellung

XRechnung, ZUGFeRD, Factur-X und Peppol BIS sind allesamt Implementierungen des europäischen semantischen Datenmodells EN 16931; ZUGFeRD und Factur-X sind technisch derselbe hybride Standard, gemeinsam von FeRD und FNFE-MPE veröffentlicht. FA(3) ist Polens eigenes Schema und keine EN-16931-Syntax. Die Formate werden unter E-Rechnungsformate verglichen; die deutsche Wahl wird unter XRechnung vs. ZUGFeRD erklärt.

Was die API zu E-Rechnungen bereitstellt

Weniger, als Sie vielleicht erwarten, und die Liste ist exakt.

• POST /invoices/drafts startet den Entwurf, der zum strukturierten Dokument wird. Er akzeptiert ausschließlich customerId.
• GET /invoices und GET /invoices/{number} liefern die eingefrorenen Werte der ausgestellten Rechnung: number, documentType, buyer, currency, issuedOn, dueOn, deliveredOn, net, tax, gross, outstanding, paymentState, overdue, cancelled, creditNote, paidOn, recordedAt.
• Der Webhook invoice.issued meldet, dass jetzt ein validiertes Dokument existiert, mit invoiceId, number, documentType, buyerName, issueDate, dueDate, currency, netMinor, taxMinor, grossMinor, amountDueMinor und paymentState.

Nicht bereitgestellt und in keinem Scope erreichbar: die XML- oder PDF-Datei selbst, der Validierungsbericht einer ausgestellten Rechnung, die Begründung des Steuerergebnisses, der Peppol- oder KSeF-Übermittlungsstatus sowie jeder Endpunkt, der ausstellt, sendet oder storniert. Die Dateien werden im Produkt heruntergeladen; die Übermittlung wird dort konfiguriert und beobachtet. Ob eine künftige Version der API den Dateidownload ergänzt, wird hier nicht versprochen.

Der kostenlose Prüfer: POST /api/v1/meta/pruefen

Der Prüfer validiert eine Datei gegen die Regeln eines Landes und antwortet mit einem strukturierten Ergebnis. Er braucht kein Konto und keinen API-Schlüssel und behält nichts — weder die Datei noch einen Digest noch eine Datenbankzeile. Er existiert, weil jedes deutsche Unternehmen seit dem 1. Januar 2025 strukturierte E-Rechnungen annehmen muss und die meisten keine Möglichkeit haben zu erkennen, ob die gerade eingetroffene gültig ist; für diese Prüfung Geld zu verlangen hieße, Geld für die Compliance selbst zu verlangen. Die Browser-Version steht unter E-Rechnung prüfen.

Die Anfrage ist multipart/form-data mit zwei Teilen: datei (die Datei) und land (der ISO-Ländercode, dessen Regeln gelten: DE, FR, BE, PL, CA oder US). Das Land ist Pflicht. Früher war Deutschland der Standardwert, und eine belgische Rechnung, die gegen deutsche Regeln geprüft wird, bekommt eine selbstbewusste Antwort, die selbstbewusst falsch ist.

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 …", "…"]
}

Die drei booleschen Werte beantworten drei verschiedene Fragen. istERechnung: Ist das überhaupt eine strukturierte E-Rechnung, im Gegensatz zu einem einfachen PDF oder einem Bild. lesbar: Konnte das Dokument als Rechnung eingelesen werden. gueltig: Besteht es die Regeln des Landes. Ein einfaches PDF ist istERechnung: false und kein Fehler. fehler und hinweise sind Listen von Befunden, jeweils mit Schweregrad, dem meldenden Validator, der Regelkennung, einem Ort und einer Meldung. leseprobleme listet Extraktionsprobleme, validatoren die tatsächlich gelaufenen Validatoren, sodass eine Teilprüfung als Teilprüfung sichtbar ist. Die Summen sind nur vorhanden, wenn das Dokument rechnerisch aufgeht; ein Dokument, das nicht aufgeht, ist bereits ein Befund, und keine Summe zu zeigen ist besser als eine Schätzung. Die Werte von format, profil und zusammenfassung hängen von der Datei ab und sind oben nur beispielhaft.

Grenzen des Prüfers

• Dateien über 25 MB werden mit 413 abgewiesen, bevor ein Byte geparst wird. Eine echte E-Rechnung mit eingebettetem XML hat wenige hundert Kilobyte.
• Anfragen werden je Client-Adresse begrenzt: ein Budget von 5 Prüfungen, das sich mit einer Prüfung pro 60 Sekunden auffüllt. Darüber hinaus lautet die Antwort 429 mit einem Retry-After-Header und einem JSON-Body, der angibt, wie lange zu warten ist. Der Prüfer ist ein Werkzeug für Menschen und gelegentliche Skripte, kein Massenvalidierungsdienst.
• Nichts wird gespeichert, daher gibt es keinen Verlauf und keinen Link zum Zurückkehren. Bewahren Sie die Antwort auf, wenn Sie sie brauchen.
• Der Prüfer validiert; er entscheidet keine Rechtsfragen. Ob ein Dokument, das besteht, in Ihrer Situation auch eine umsatzsteuerlich korrekte Rechnung ist, erfordert eine fachliche Bestätigung.

Strukturierte Rechnungen empfangen

Dieselben Leser, die hinter dem Prüfer stehen, werden im Produkt verwendet: Eingehende XRechnung-, ZUGFeRD/Factur-X- und UBL-Dokumente werden mit Lieferant, Nummer, Datum und Summen als Eingangsrechnungen eingelesen, und ihr Validierungsergebnis wird mit der Eingangsrechnung gespeichert. Dieser Eingangspfad ist heute nicht über die öffentliche API zugänglich; im Produkt erfasste Eingangsrechnungen werden nach außen über den Webhook purchase.recorded gemeldet, mit purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor und grossMinor. Die deutschen Empfangspflichten werden unter E-Rechnungen empfangen in Deutschland erklärt.

Wie KRONENWERK das handhabt

MIT EINSCHRÄNKUNGEN UNTERSTÜTZT Erzeugung und Validierung von XRechnung, ZUGFeRD, Factur-X, Peppol BIS UBL und FA(3) bei der Ausstellung sind Teil des Produkts (E-Rechnung). Der Anteil der API daran sind der Entwurf, das Auslesen und der Webhook, im Enterprise-Plan (Preise). Der Prüfer ist für alle kostenlos. Die Einschränkungen liegen beim Transport: Senden und Empfangen über Peppol laufen über einen akkreditierten Access-Point-Anbieter (Storecove), sobald das Unternehmen unter Einstellungen → Zustellung angebunden ist — KRONENWERK ist selbst kein Peppol Access Point; die französische Übermittlung über eine plateforme agréée ist über die Fähigkeit von Storecove als zugelassene Plattform geplant und noch nicht produktionsreif; das polnische KSeF-2.0-Modul wurde nicht gegen das produktive KSeF eingesetzt. Jedes Thema hat eine eigene Seite: Peppol-Integration, KSeF-Integration und der Formatleitfaden für Entwickler unter EN 16931 für Entwickler.