E-Rechnung API und Dokumentation für Entwickler: Der technische Einstieg

Kurz & knapp: Wer E-Rechnungsfunktionen selbst programmatisch in ein Produkt oder eine interne Anwendung integrieren will, benötigt drei Dinge: die offizielle Spezifikation des zugrunde liegenden Standards EN 16931, Zugriff auf ein Validierungswerkzeug wie den KoSIT-Validator sowie ein sauberes Verständnis der beiden relevanten Zielformate XRechnung und ZUGFeRD. Dieser Artikel bündelt die zentralen technischen Anlaufpunkte und typischen Implementierungsmuster für Entwicklerinnen und Entwickler.

Ausgangslage: Was Entwickler technisch umsetzen müssen

Die deutsche E-Rechnungspflicht basiert auf dem Wachstumschancengesetz und der entsprechenden Änderung des § 14 UStG. Seit dem 1. Januar 2025 müssen Unternehmen elektronische Rechnungen empfangen können, ab dem 1. Januar 2027 greift die Ausstellungspflicht für Unternehmen mit einem Vorjahresumsatz über 800.000 Euro, ab dem 1. Januar 2028 gilt sie universell. Für Softwareentwickler, die eine eigene Rechnungserzeugung, ein Buchhaltungsmodul oder eine Validierungsfunktion bauen, bedeutet das konkret: Ausgangsrechnungen müssen als strukturierte, maschinenlesbare Datensätze nach dem europäischen Standard EN 16931 erzeugt werden können, und eingehende Belege in diesem Format müssen zuverlässig geparst und verarbeitet werden können.

Der zugrunde liegende Standard: EN 16931

Kern aller relevanten Formate ist die europäische Norm EN 16931, die ein semantisches Datenmodell für elektronische Rechnungen definiert – also festlegt, welche Informationen (Rechnungssteller, Leistungsempfänger, Positionen, Steuersätze, Zahlungsbedingungen und weitere Pflicht- und Kannfelder) enthalten sein müssen und in welcher Beziehung sie zueinanderstehen. Aus diesem semantischen Modell leiten sich zwei konkrete technische Syntaxen ab, in denen die deutschen Formate umgesetzt werden können: UBL (Universal Business Language) und CII (Cross Industry Invoice). Für die technische Umsetzung ist es entscheidend, sich zunächst mit dem semantischen Modell vertraut zu machen, bevor man sich für eine der beiden Syntaxen entscheidet, da viele Validierungsfehler in der Praxis aus einem falschen Verständnis der zugrunde liegenden Feldsemantik entstehen.

XRechnung versus ZUGFeRD aus Entwicklersicht

XRechnung ist ein rein strukturiertes XML-Dokument ohne visuelle Darstellungskomponente, das in der Regel in UBL- oder CII-Syntax vorliegt. ZUGFeRD kombiniert dagegen ein PDF/A-3-Dokument mit eingebettetem XML nach demselben semantischen Modell, sodass die Datei sowohl maschinell verarbeitet als auch von Menschen direkt gelesen werden kann. Für Entwickler bedeutet die Implementierung von ZUGFeRD zusätzlichen Aufwand, da neben der XML-Erzeugung auch eine PDF/A-3-konforme Darstellung mit korrektem Einbetten des XML-Anhangs realisiert werden muss – hierfür existieren spezialisierte Bibliotheken, deren Eignung und Lizenzbedingungen im Einzelfall geprüft werden sollten.

Offizielle technische Dokumentation als erste Anlaufstelle

Für die verbindliche technische Spezifikation von XRechnung ist die vom IT-Planungsrat beauftragte Koordinierungsstelle für IT-Standards (KoSIT) die zentrale Quelle. Dort werden die offiziellen Spezifikationsdokumente, Schematron-Regeln und Beispieldateien für die jeweils aktuelle Version veröffentlicht. Für ZUGFeRD ist der Ferd e.V. (Forum elektronische Rechnung Deutschland) die tragende Organisation, die die Spezifikation gemeinsam mit dem französischen Pendant (dort unter dem Namen Factur-X) pflegt. Entwickler sollten sich grundsätzlich an der jeweils aktuellen offiziellen Version orientieren, da sich Feldanforderungen und Validierungsregeln zwischen Versionen ändern können.

Validierung: Der KoSIT-Validator als zentrales Werkzeug

Um sicherzustellen, dass ein selbst erzeugtes Dokument tatsächlich normkonform ist, stellt die KoSIT einen offiziellen Validator bereit, der Rechnungen gegen die Schematron-Regeln des XRechnung-Standards prüft. Dieses Werkzeug lässt sich sowohl über eine grafische Oberfläche als auch kommandozeilenbasiert beziehungsweise im Rahmen automatisierter Testpipelines einsetzen. Für Entwickler empfiehlt es sich dringend, diesen Validator von Beginn an in die eigene Continuous-Integration-Pipeline einzubinden, sodass jede Änderung am Rechnungserzeugungscode automatisch gegen aktuelle Validierungsregeln geprüft wird, statt Fehler erst im späteren manuellen Test oder – schlimmer noch – erst beim Kunden zu entdecken.

Typische Architektur einer Rechnungserzeugungs-API

In der Praxis haben sich für die programmatische Erzeugung von E-Rechnungen ähnliche Architekturmuster etabliert, unabhängig vom konkreten Technologie-Stack. Eine Anwendung nimmt strukturierte Rechnungsdaten entgegen (etwa als internes Objektmodell oder JSON), validiert diese zunächst fachlich auf Vollständigkeit der Pflichtfelder, mappt sie anschließend auf das Zielschema (UBL oder CII) und erzeugt daraus das XML-Dokument. Bei ZUGFeRD folgt ein zusätzlicher Schritt, in dem das erzeugte XML in ein PDF/A-3-Dokument eingebettet wird. Vor der Auslieferung oder dem Versand sollte das erzeugte Dokument programmatisch gegen die offiziellen Schematron-Regeln validiert werden, idealerweise automatisiert innerhalb derselben Verarbeitungskette.

Typische Architektur einer Empfangs- und Parsing-Komponente

Für die Verarbeitung eingehender E-Rechnungen ist der umgekehrte Weg zu implementieren: Ein eingehendes Dokument – XML-Datei oder PDF/A-3 mit eingebettetem XML – wird zunächst auf Wohlgeformtheit geprüft, das enthaltene XML extrahiert (bei ZUGFeRD aus dem PDF-Container) und gegen das Schema validiert. Anschließend werden die enthaltenen Daten in ein internes Datenmodell überführt, das für die Weiterverarbeitung – etwa eine automatisierte Buchungsvorschlagslogik oder die Anzeige in einer Prüfoberfläche – genutzt wird. Robuste Implementierungen behandeln dabei auch fehlerhafte oder unvollständige eingehende Dokumente sauber, statt bei Abweichungen vom Erwartungswert abzustürzen.

Praxisbeispiel: Kellerhoff Software GmbH

Die fiktive Kellerhoff Software GmbH entwickelt eine Branchenlösung für Handwerksbetriebe und musste im Rahmen eines Produkt-Updates eine eigene E-Rechnungsfunktion in ihre Anwendung integrieren, da eine Anbindung an externe Drittanbieter für das Preismodell des Produkts nicht infrage kam. Das Entwicklerteam begann mit einem gründlichen Studium der EN-16931-Spezifikation und der offiziellen KoSIT-Dokumentation zu XRechnung, bevor mit der Implementierung begonnen wurde. Für die Formaterzeugung entschied sich das Team für die UBL-Syntax, da die vorhandenen internen Datenstrukturen sich einfacher darauf abbilden ließen. Der KoSIT-Validator wurde direkt in die automatisierten Tests der Continuous-Integration-Pipeline eingebunden, sodass jede Codeänderung sofort gegen aktuelle Validierungsregeln geprüft wurde. Für ZUGFeRD, das als Zusatzoption für kleinere Handwerksbetriebe angeboten werden sollte, wurde zusätzlich eine spezialisierte Bibliothek zur PDF/A-3-Einbettung evaluiert und in einem separaten Modul integriert.

Checkliste für den Entwicklungsstart

• Aktuelle Version der EN-16931-Spezifikation und der nationalen XRechnung-Spezifikation der KoSIT beschafft
• Entscheidung für UBL- oder CII-Syntax getroffen und begründet dokumentiert
• KoSIT-Validator lokal und in der CI-Pipeline eingebunden
• Testdatensätze mit Sonderfällen (mehrere Steuersätze, Rabatte, Gutschriften) erstellt
• Bei ZUGFeRD: geeignete Bibliothek für PDF/A-3-Erzeugung und XML-Einbettung evaluiert
• Fehlerbehandlung für nicht valide eingehende Dokumente konzipiert
• Prozess zur Nachverfolgung neuer Spezifikationsversionen etabliert

Typische technische Fehler in eigenen Implementierungen

Ein häufiger Fehler ist die unvollständige Abbildung von Pflichtfeldern, insbesondere bei Sonderfällen wie mehreren Steuersätzen auf einer Rechnung, Skonto-Angaben oder Korrekturrechnungen, die im Testdatensatz oft nicht ausreichend abgedeckt werden. Ein zweiter verbreiteter Fehler betrifft die Zeichenkodierung und Sonderzeichen in Freitextfeldern, die bei unsauberer Implementierung zu ungültigem XML führen können. Auch die Leitweg-ID, die bei Rechnungen an öffentliche Auftraggeber zwingend erforderlich ist, wird in eigenen Implementierungen gelegentlich vergessen oder falsch validiert. Schließlich unterschätzen viele Teams den Pflegeaufwand: Da sich Spezifikationen weiterentwickeln, sollte die Validierungslogik nicht als einmalig fertiggestellt, sondern als dauerhaft zu wartender Codebestandteil eingeplant werden.

Umgang mit Randfällen und Erweiterungen

Neben dem Standardfall einer einzelnen B2B-Rechnung gibt es technische Randfälle, die eigene Implementierungen von Anfang an berücksichtigen sollten: Sammelrechnungen mit vielen Positionen, Teilrechnungen bei Werkverträgen, Rechnungen mit gemischten Steuersätzen (etwa bei kombinierten Liefer- und Dienstleistungen) sowie die korrekte Abbildung von Anzahlungen und deren späterer Verrechnung. Auch länderspezifische Erweiterungen jenseits des deutschen Kernstandards – etwa wenn ein Produkt später auch in anderen EU-Ländern eingesetzt werden soll – sollten architektonisch von Beginn an mitgedacht werden, auch wenn sie nicht sofort implementiert werden.

Peppol-Integration aus Entwicklersicht

Wer eine eigene Anwendung nicht nur zur Formaterzeugung, sondern auch zur direkten Übertragung von Rechnungen befähigen möchte, kommt am europäischen Peppol-Netzwerk kaum vorbei. Peppol definiert neben dem eigentlichen Rechnungsformat auch standardisierte Transportprotokolle und ein Verzeichnis, über das Teilnehmer anhand einer eindeutigen Kennung gefunden werden können. Für Entwickler bedeutet eine Peppol-Anbindung in der Regel nicht, selbst einen vollständigen Access Point zu betreiben, sondern sich technisch an einen bestehenden zertifizierten Zugangspunkt anzubinden, der die Signierung, Verschlüsselung und das eigentliche Routing der Nachrichten übernimmt. Die eigene Anwendung liefert dabei das validierte Rechnungsdokument und die Metadaten zur Zustellung an diesen Zugangspunkt und erhält im Gegenzug Statusrückmeldungen über Zustellung oder Ablehnung, die in die eigene Anwendungslogik zurückgespielt werden sollten.

Bibliotheken, Frameworks und Eigenentwicklung abwägen

Bevor ein Entwicklerteam mit der Implementierung beginnt, lohnt sich eine bewusste Build-or-Buy-Entscheidung. Für gängige Programmiersprachen existieren mittlerweile Open-Source- und kommerzielle Bibliotheken, die Teile der XML-Erzeugung, der PDF/A-3-Einbettung bei ZUGFeRD oder der Schema-Validierung bereits abdecken. Diese Bibliotheken können erheblichen Entwicklungsaufwand sparen, sollten aber sorgfältig hinsichtlich Aktualität, Lizenzbedingungen und tatsächlicher Konformität mit der jeweils aktuellen Spezifikationsversion geprüft werden, bevor sie produktiv eingesetzt werden. Eine vollständige Eigenentwicklung aller Komponenten bietet zwar maximale Kontrolle, bindet aber dauerhaft Entwicklungskapazität für die Pflege bei jeder Spezifikationsänderung – eine Abwägung, die früh im Projekt getroffen werden sollte, statt sie erst bei den ersten Validierungsfehlern im Produktivbetrieb zu treffen.

Fazit

Die programmatische Erzeugung und Verarbeitung von E-Rechnungen ist technisch klar spezifiziert, aber im Detail anspruchsvoll. Entwickler sollten sich konsequent an den offiziellen Quellen – der EN-16931-Spezifikation, der KoSIT-Dokumentation für XRechnung und dem Ferd e.V. für ZUGFeRD – orientieren und den offiziellen Validator von Beginn an in die eigene Entwicklungs- und Testpipeline integrieren. Wer diese Grundlagen sauber legt, vermeidet die typischen Validierungsfehler, die in der Praxis für den größten Nacharbeitsaufwand sorgen.

Häufig gestellte Fragen

Wo finde ich die offizielle technische Spezifikation für XRechnung?

Die maßgebliche Quelle ist die KoSIT (Koordinierungsstelle für IT-Standards), die die Spezifikation, Schematron-Regeln und Beispieldateien veröffentlicht.

Soll ich UBL oder CII als Syntax verwenden?

Beide Syntaxen sind zulässig und bilden dasselbe semantische Modell ab. Die Wahl hängt meist davon ab, welche Syntax sich einfacher auf die eigenen internen Datenstrukturen abbilden lässt.

Reicht der KoSIT-Validator zur vollständigen Qualitätssicherung aus?

Er prüft die formale Konformität zum Schema zuverlässig, ersetzt aber keine fachliche Prüfung, ob alle inhaltlich relevanten Rechnungsdaten korrekt und vollständig übernommen wurden.

Wie implementiere ich ZUGFeRD zusätzlich zu XRechnung?

Sie benötigen eine zusätzliche Komponente, die das erzeugte XML normkonform in ein PDF/A-3-Dokument einbettet. Hierfür gibt es spezialisierte Bibliotheken, deren Lizenzmodell Sie prüfen sollten.

Wie gehe ich mit sich ändernden Spezifikationsversionen um?

Etablieren Sie einen festen Prozess, der neue Versionen der Spezifikation und des Validators regelmäßig prüft und die eigene Implementierung entsprechend anpasst.

Was ist die Leitweg-ID und wann brauche ich sie?

Die Leitweg-ID identifiziert den Empfänger bei Rechnungen an öffentliche Auftraggeber und ist dort ein Pflichtfeld, das in der eigenen Implementierung korrekt abgebildet werden muss.

Kann ich meine Implementierung gegen echte Testfälle prüfen?

Ja, sowohl KoSIT als auch Ferd e.V. stellen Beispieldateien und Testfälle bereit, die sich für automatisierte Regressionstests der eigenen Implementierung eignen.