XRechnung validieren: typische Fehler und ihre API-Lösung

Warum Validierung kritisch ist

Seit dem 1. Januar 2025 sind deutsche Unternehmen im B2B-Bereich verpflichtet, strukturierte E-Rechnungen empfangen zu können. Das Peppol-Netzwerk und die Leitweg-ID-Pflicht im öffentlichen Sektor bestehen schon länger. Eine Rechnung, die die XRechnung-Schemata nicht erfüllt, wird von behördlichen Empfangssystemen (z. B. ZRE oder OZG-RE) schlicht abgelehnt.

Validierungsfehler sind teuer: Bei manuellen Prozessen bedeutet eine abgelehnte Rechnung Nacharbeit, Zahlungsverzug und Support-Aufwand. Wer XRechnungen programmatisch erzeugt, braucht deshalb eine automatisierte Validierung als festen Schritt in der Erzeugungspipeline.

Die 5 häufigsten Fehler bei XRechnungen

Aus tausenden validierten Dokumenten haben sich fünf Fehlerkategorien als besonders häufig erwiesen:

• → Falsche oder fehlende CustomizationID – XRechnung UBL erwartet exakt urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0 (Stand 3.x). Abweichende Werte führen zu einem sofortigen Schema-Reject.
• → Fehlende Pflichtfelder gemäß EN 16931 – Besonders BT-9 (Fälligkeitsdatum), BT-25 (Rechnungsperiode) und BT-31/32 (Steuernummer / USt-IdNr. des Verkäufers) werden häufig vergessen.
• → Ungültige Steuerbehandlung – Fehlende oder widersprüchliche TaxCategory-Codes. Steuerbefreite Leistungen (z. B. §4 UStG) müssen mit Code E und einem AEW-Reason codiert werden.
• → Datumsformat-Fehler – XRechnung erwartet ISO-8601 (YYYY-MM-DD). Timestamps mit Uhrzeit oder lokalisierte Datumsformate wie 01.04.2025 werden abgewiesen.
• → Summen-Inkonsistenzen – TaxExclusiveAmount + TaxAmount muss exakt TaxInclusiveAmount ergeben. Rundungsdifferenzen durch Float-Arithmetik sind ein klassischer Fallstrick.

XRechnung im Browser validieren

Für manuelle Tests eignet sich der kostenlose Web-Validator auf dieser Seite. Du lädst die XML-Datei hoch und erhältst (nach kostenloser Registrierung) sofort strukturierte Fehlermeldungen mit Business-Term-Referenz (z. B. BR-31), Pfad im Dokument und einer menschenlesbaren Beschreibung. Ohne Registrierung bekommst du eine einfache Status-Anzeige ohne Details.

Für den Produktivbetrieb ist das Web-Interface nicht geeignet. Sobald mehr als einzelne Test-Rechnungen anfallen, brauchst du die API.

Validierung per API – curl-Beispiel

Mit der XInvoice API lässt sich eine XRechnung mit einem einzelnen HTTP-POST validieren. Das Ergebnis enthält strukturierte Fehler nach EN 16931 Business Rules:

curl -X POST https://api.xinvoice.net/v1/invoices/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @rechnung.xml

Die Antwort enthält ein strukturiertes JSON-Objekt mit valid tue/false, einer Liste von errors (mit rule-ID, xpath und message) sowie einem warnings-Array für Hinweise ohne Reject-Wirkung.

Validierung in die Pipeline integrieren

Der typische Einsatz sieht so aus: Dein ERP oder deine Faktura-Software erzeugt das XML. Vor der Übermittlung an die ZRE oder den Kunden wird das Dokument per API validiert. Nur bei valid: true wird die Rechnung weitergeleitet, sonst wird ein internes Fehler-Ticket erzeugt.

So sind Rückweisungen durch Behörden ausgeschlossen, bevor die Rechnung das Haus verlässt. Die XInvoice API gibt dir dafür 100 kostenlose Calls in den ersten 30 Tagen – für Integration und Tests mehr als ausreichend.

Durch den Verzicht auf einen Webhook hast du weniger Integrationsaufwand. Stattdessen wiederholt deine Anwendung den Request auf den GET-Endpunkt so lange, bis der Status "generated" (oder "failed") zurückkommt. Bei "generated" wird die fertige XML-Datei sofort mitgesendet.

Alternativ kann der generate-Aufruf auch asynchron gestaltet werden – deine Software wartet dann einfach auf die fertige Rechnung (typischerweise ca. 3 Sekunden).