XRechnung API Anbindung: Architektur, JSON & Validierung

XRechnung API Anbindung: Architektur, JSON Mapping und Validierungs-Gates

Viele Entwicklerteams und Systemarchitekten stehen vor der Aufgabe, ein hauseigenes ERP, ein SaaS-CRM oder einen E-Commerce-Shop "schnell mal XRechnung-fähig" zu machen. Der oft tödliche Fehler: Sie versuchen, die hochkomplexe europäische XML-Norm (EN 16931) hart in den eigenen Codebase zu hämmern.

Die weitaus belastbarere Integrationsstrategie ist der Aufbau oder die Nutzung einer REST-API, bei der das Host-System simple JSON-Daten feuert und die E-Rechnungs-Logik inklusive Syntaxauswertung völlig abgekapselt in einem Microservice (oder bei einem Dritthersteller) läuft.

In diesem IT-Guide zeigen wir Ihnen die Best Practices für eine ausfallsichere XRechnungs-Architektur.

Direktantwort: So sieht eine moderne XRechnung-Architektur aus

Eine stabile, asynchrone API-Anbindung für XRechnungen besteht aus diesen Schichten:

1. Source Layer (Das Host-System): Sendet einen reinen POST-Request mit strukturierten JSON-Rechnungsdaten (Beträge, Artikel, Absender).
2. Mapping Layer: Ein Microservice übersetzt die simplen Schlüssel/Wert-Paare in das tiefe, eklige XML-Schema-Routing (XSD-Blaupause) der XRechnung (UBL oder CII Format).
3. Validation Gate: Die frisch generierte XML durchläuft noch Server-seitig eine KoSIT-Validierung (Business Rules Deutschland). Fällt sie durch BR-DE Fehler durch, feuert die API sofort einen 400 Bad Request an das Source Layer zurück.
4. Delivery Layer: Erst bei "grünem Licht" (200 OK) im Validation Gate geht die Rechnung ins Peppol-Netzwerk oder per Mail raus.

Wenn Sie genau dieses Validierungs-Gate nicht selbst betreiben möchten, lesen Sie die Details zur KoSIT Validator API für E-Rechnung, XRechnung und ZUGFeRD.

Endpunkt-Design: Best Practices für Rechnungs-APIs

Verzichten Sie auf monolithische /generate_invoice Aufrufe, die 3 Minuten hängen. Setzen Sie auf Ressourcen-Basierung.

* POST /api/v1/invoices: Erstellt die Rechnung aus dem JSON-Payload. Antwortet bei Erfolg mit 201 Created und der ID der generierten XRechnung.
* GET /api/v1/invoices/{id}/status: Zum Polling, wenn der Validierungs- und Versandprozess asynchron (Queue) im Server läuft.
* GET /api/v1/invoices/{id}/xml: Endpunkt zum Download der nativen .xml Datei für Ihr eigenes revisionssicheres Host-Archiv gemäß GoBD Leitlinien.

Das Wichtigste: Fehlerbehandlung (HTTP 400er)

Gute APIs fangen nicht nur Code-Ausfälle ab, sondern mappen die fachlichen KoSIT-Fehler auf die JSON-Response. Statt eines törichten 500 Server Error, wenn der Kunde die Leitweg-ID für B2G vergisst, muss Ihre API ein strukturiertes Error-Array zurückbringen, zum Beispiel: {"error": "Validation Failed", "code": "BR-DE-15", "details": "Buyer Reference (BT-10) is missing."}

Das Herzstück: JSON-to-XML Mapping

Der schwerste Teil der API-Entwicklung ist das XSD Schema Mapping. Die EU Norm erwartet Daten in tief verschachtelten Taxonomien.

Beispiel für ein API Mapping einer Auftraggeber referenz (BT-10):
Ihr Source-Shop feuert vielleicht simpel:

json
{
  "customer_reference": "04011000-12345-67"
}

Die Mapping-Logik in Ihrem API Broker muss wissen, wo das korrespondierende XML-Äquivalent in UBL liegt:

xml

   ... 

04011000-12345-67

Lagern Sie dieses Mapping unbedingt in config-Dateien oder nutzen Sie externe Mapping-Engines, da sich die XRechnungs-Syntaxen regelmäßig ändern (Major/Minor Updates der KoSIT).

Typische Coder-Stolpersteine bei E-Rechnungs-APIs

## Make or Buy: API selber bauen oder einkaufen?

Sollten Sie die komplette XRechnungs-Logik selbst hosten?

* Selbst bauen: Lohnt sich nur bei Startups, die XRechnungs-Versand als Kernprodukt Ihres eigenen SaaS für Steuerberater vertreiben. Hier rechnet sich der monatelange XSD-Mapping Wahnsinn.
* REST API einkaufen (Middleware): Für Webshops, Agentursoftware-Hersteller oder Legacy-ERP-Betreiber der absolut beste Weg. Sie schicken Ihr simples JSON-Objekt an eine Provider-API, diese generiert und validiert die Datei und wirft die fertige EU-Norm in Ihre Server zurück.

Fazit: Die API als Schutzschild

Der größte Wert einer sauberen XRechnungs-API ist ihr "Schutzschild-Charakter". Durch ein hartes Validierungs-Gateway in der REST Architektur verhindern Sie strukturell, dass Ihr Vertrieb oder Shopsystem fehlerhafte Rechnungen an Kunden oder das B2G Portal feuert. Wenn Ihr Mapping und die JSON Validierung stehen, läuft die XML Generierung zu 100% wartungsfrei.