Invoice Services API …

Health … Swagger OpenAPI Capabilities

1 · Eingangsdokument

Beispiel Datei XML-Text

Kein Dokument geladen.

2 · Kanonische Rechnung (JSON)

Eingabe für generate und für render aus dem Modell. Füllt sich bei Bedarf selbst über read und muss nicht von Hand bedient werden — die Konsole erzeugt keine Rechnungsdaten, sie zeigt hier die der API.

leer

3 · Operation

4 · Ergebnis

Noch nichts ausgeführt.

Kein erzeugtes Dokument.

Verlauf

Jeder Eintrag lässt sich aufklappen und zeigt die gesendete Anfrage, die Kopfzeilen und die Antwort der API im Wortlaut. Base64-Inhalte stehen als Größenangabe da, damit ein Dokument den Verlauf nicht unlesbar macht.

Noch nichts aufgezeichnet.

Wie diese Konsole zu bedienen ist

Der Grundgedanke

Der Dienst kennt genau zwei Gegenstände, und jede Operation ist nur ein Weg zwischen ihnen. Wer das einmal vor Augen hat, braucht für den Rest keine Anleitung mehr.

Dokument: Eine Datei, wie sie zwischen Unternehmen verschickt wird — XML-Instanz oder hybrides PDF, in einem bestimmten Format, Profil und einer bestimmten Syntax. Das ist Feld 1.
Kanonische Rechnung: Derselbe fachliche Inhalt ohne Syntax, als JSON entlang der Business Terms der EN 16931 — BT-1 Rechnungsnummer, BT-27 Verkäufername und so fort. Ein Modell für alle Formate. Das ist Feld 2.

    Datei / XML                        JSON
  ┌──────────────┐              ┌────────────────┐
  │   DOKUMENT   │─── lesen ───▶│   KANONISCHE   │
  │   (Feld 1)   │◀── erzeugen ─│    RECHNUNG    │
  └──────────────┘              │    (Feld 2)    │
     │       │                  └────────────────┘
     │       └─── konvertieren ───▶ Dokument         │
     │                                               │
     └── validieren ──▶ Urteil   darstellen ◀────────┘
                                       │
                                  HTML / PDF

„Konvertieren“ ist keine eigene Fähigkeit, sondern lesen und erzeugen in einem Aufruf. Deshalb kann konvertiert werden, was auch gelesen werden kann — und nur das.

Die Begriffe auf einen Blick

Die Namen im Umlauf bezeichnen Dinge auf sehr verschiedenen Ebenen — ein Datenmodell, eine XML-Grammatik, ein Dateiformat, eine Prüftechnik. Wer sie nebeneinanderstellt, sieht, dass sie einander nicht ausschließen, sondern aufeinander aufbauen.

Begriff	Was ist es?	Typisches Format
EN 16931	Europäisches semantisches Datenmodell für E-Rechnungen	noch keine konkrete Datei
UBL 2.1	XML-Syntax für Rechnungen (OASIS)	XML
UN/CEFACT CII	Zweite zugelassene XML-Syntax	XML
XRechnung	Deutsche CIUS-Ausprägung von EN 16931, besonders für Behörden	reines XML
ZUGFeRD	Hybride Rechnung aus lesbarem PDF und strukturiertem XML	PDF/A-3 + CII-XML
Peppol BIS Billing	Europäische Spezifikation für Rechnungsdaten und den Peppol-Austausch	meist UBL-XML
Schematron	Geschäftsregeln zur Prüfung — keine Rechnung, sondern Prüfregeln	Regeldateien

Peppol BIS Billing steht hier zur Einordnung. Dieser Dienst unterstützt es nicht; was er kann, sagt die Aufstellung weiter unten und /v1/capabilities.

EN 16931 — das Fundament

Die Norm legt die fachliche Bedeutung der Rechnungsdaten fest, nicht deren Schreibweise: Rechnungsnummer, Rechnungsdatum, Verkäufer und Käufer, Umsatzsteuer-Identifikationsnummer, Positionen, Mengen und Preise, Steuersätze, Zahlungsbedingungen, Zahlbetrag, Bestellreferenz. Jede dieser Angaben trägt eine Kennung, einen Business Term.

Business Term	Bedeutung
BT-1	Rechnungsnummer
BT-2	Rechnungsdatum
BT-3	Rechnungsart (Code aus UNTDID 1001)
BT-10	Buyer Reference — in Deutschland die Leitweg-ID
BT-20	Zahlungsbedingungen
BT-24	Spezifikationskennung (`CustomizationID`)
BT-27	Name des Verkäufers
BT-44	Name des Käufers
BT-146	Nettopreis der Position

EN 16931 ist damit das Datenmodell, nicht das XML-Format. Für die Schreibweise sind zwei Syntaxen zugelassen, UBL und UN/CEFACT CII. Genau dieses Modell ist die kanonische Rechnung in Feld 2 — deshalb lässt sich daraus in jedes unterstützte Format schreiben.

XRechnung — die deutsche CIUS

CIUS heißt „Core Invoice Usage Specification“: eine Ausprägung, die das europäische Modell einschränkt und konkretisiert, ohne es zu erweitern. Was eine XRechnung erfüllt, erfüllt damit stets auch die EN 16931.

strukturiertes XML, ohne verpflichtende PDF-Ansicht
in beiden Syntaxen verfügbar, UBL und CII
zusätzliche deutsche Regeln und Pflichtfelder (BR-DE-…)
besonders relevant für Rechnungen an die öffentliche Hand (B2G)

Für Behördenrechnungen kommen je nach Empfänger weitere Angaben hinzu: Leitweg-ID, Bestell- oder Vertragsnummer, passende Zahlungs- und Adressdaten. Die Leitweg-ID wird grundsätzlich nur für Rechnungen an Behörden benötigt, nicht im gewöhnlichen B2B-Verkehr.

ZUGFeRD — hybrid

PDF/A-3
  └── eingebettete strukturierte XML-Rechnung
        └── UN/CEFACT CII

Der Empfänger sieht ein gewöhnliches PDF; die Buchhaltung liest zugleich die eingebetteten XML-Daten. Das PDF ist dabei nicht der führende Teil. Weichen Ansicht und Daten voneinander ab, sind die strukturierten XML-Daten maßgeblich.

ZUGFeRD ist inhaltsgleich mit Factur-X — dieselbe Spezifikation unter deutschem und französischem Namen.

Zur steuerlichen Eignung: Das Bundesfinanzministerium nennt ZUGFeRD ab Version 2.0.1 grundsätzlich als geeignetes Format, schließt die Profile MINIMUM und BASIC WL davon aber aus. Das deckt sich mit dem, was dieser Dienst technisch zulässt — beide Profile tragen keine Rechnungspositionen und lassen sich deshalb weder lesen noch erzeugen noch konvertieren, wohl aber prüfen und anzeigen.

XRechnung oder ZUGFeRD?

Anwendungsfall	Besser geeignet
Rechnung an Bund, Land oder Kommune	XRechnung
Rechnung an ein Unternehmen	beide
Ein Mensch soll zusätzlich ein PDF lesen können	ZUGFeRD
Automatische Verarbeitung im ERP	beide
Maximale Einfachheit beim XML	XRechnung
Peppol-Netzwerk	meist UBL / Peppol BIS

XRechnung ist im B2B-Bereich nicht generell vorgeschrieben, aber zulässig. Im B2G-Bereich entscheidet zusätzlich das jeweilige Portal oder die Behörde über akzeptierte Formate und Übermittlungswege.

Fristen in Deutschland

Für inländische B2B-Umsätze gilt nach den Vorgaben des Bundesfinanzministeriums:

Seit dem 1. Januar 2025 müssen Unternehmen E-Rechnungen empfangen können; dafür genügt grundsätzlich ein E-Mail-Postfach.
Bis Ende 2026 dürfen viele Unternehmen noch Papier- oder PDF-Rechnungen ausstellen.
Bei einem Vorjahresumsatz bis 800.000 € reicht die Übergangsfrist bis Ende 2027.
Ab 2028 ist die E-Rechnung für die betroffenen inländischen B2B-Umsätze grundsätzlich verpflichtend.

Ein gewöhnliches PDF ist keine strukturierte E-Rechnung. Diese Angaben dienen der Einordnung und ersetzen keine rechtliche Beratung; maßgeblich sind die Veröffentlichungen des BMF sowie für XRechnung die der KoSIT.

Wie dieser Dienst dazu steht

Ein einziges internes Rechnungsmodell auf Basis der EN-16931-Business-Terms, aus dem alle Formate erzeugt werden — XRechnung in UBL und CII, ZUGFeRD als CII in PDF/A-3. XRechnung und ZUGFeRD sind ausdrücklich nicht als zwei getrennte Datenmodelle gebaut; das ist die kanonische Rechnung aus Feld 2.

Geprüft wird gestaffelt: XSD, dann die EN-16931-Schematron-Regeln, dann die Regeln des erkannten Formats, bei ZUGFeRD zusätzlich PDF/A-3 und die Übereinstimmung von PDF und eingebettetem XML. Die Fassungen sind gepinnt und unten aufgeführt.

Nicht Teil dieses Dienstes ist der Versand — E-Mail, Peppol, Behördenportale, EDI. Das gehört in ein eigenes Modul und wird hier bewusst nicht vorgetäuscht.

Die Operationen

Die Auswahl in Feld 3 stammt aus /v1/capabilities. Dropdowns erscheinen nur dort, wo eine Entscheidung nötig ist: beim Validieren und Lesen ist das Ziel durch das Dokument bereits bestimmt.

Feld 1 · Eingangsdokument

Beispiel, Datei oder XML-Text — drei Wege, dieselbe Sache zu laden; danach ist der Ablauf identisch. Der Beispielkatalog enthält die offiziellen Testbestände der gepinnten Fassungen und steht nur im Development-Profil zur Verfügung.

Was das Dokument ist, gibst du nirgends an. Format, Version, Profil und Syntax erkennt die API selbst und nennt sie in der Antwort als detectedRepresentation. Eine Auswahl dafür wäre eine Behauptung über genau die Frage, die der Dienst beantworten soll.

Feld 2 · Kanonische Rechnung

Füllt sich selbst: Wählst du eine Operation, die eine kanonische Rechnung braucht, und ist das Feld leer, ruft die Konsole zuvor read auf und zeigt das Ergebnis hier. Von Hand brauchst du es nur, wenn du ohne Ausgangsdokument eine Rechnung erzeugen oder vor dem Erzeugen etwas ändern willst. Ist das Feld gefüllt, bleibt es unangetastet — dann ist es die Eingabe.

Validieren — die Reihenfolge ist normativ

XSD — ist es syntaktisch das, was es vorgibt zu sein?
EN 16931 — die europäischen Geschäftsregeln (BR-…, BR-CO-…).
Regeln des erkannten Formats — XRechnung (BR-DE-…, PEPPOL-…) oder ZUGFeRD.

Eine XSD-Prüfung allein genügt ausdrücklich nicht. Ein Dokument kann schemakonform und fachlich falsch sein; die meisten echten Fehler liegen auf Stufe 2 und 3.

Standards, Profile und Syntaxen

Ein Profil ist ein Ausschnitt des Standards — wie viel Inhalt eine Rechnung mindestens trägt. Eine Syntax ist die XML-Grammatik: dieselbe Rechnung, andere Elementnamen. Welche Kombination wofür zulässig ist, sagt die folgende Aufstellung, und sie kommt aus dem Dienst selbst.

„(Vorgabe der API)“

Der erste Eintrag in Profil und Syntax heißt: nichts mitschicken, der Dienst entscheidet. Eine Ausnahme ist zu kennen — beim Erzeugen einer XRechnung gibt es serverseitig keine Syntax-Vorgabe, weil die Norm beide zulässt; die Anfrage scheiterte dann mit 422 … requires an explicit UBL or CII syntax. Deshalb stellt die Konsole die Syntax vorab auf den ersten Wert der Liste des Dienstes. Beim Profil bleibt die Vorgabe stehen, denn dort hat die API eine.

Darstellen ist eine Ansicht, keine Rechnung

Quelle bestimmt, was dargestellt wird — das Dokument aus Feld 1 oder die Rechnung aus Feld 2. Ausgabe bestimmt HTML oder PDF. Das Ergebnis trägt isVisualizationOnly: es ist zum Ansehen da und keine Rechnung im Rechtssinne.

Ein PDF, das die Daten mitträgt und selbst eine gültige Rechnung ist, entsteht über Erzeugen oder Konvertieren mit dem Zielstandard ZUGFeRD — nicht über Darstellen.

Feld 4 · Ergebnis und Verlauf

Übersicht: Erkanntes Format, Urteil, Meldungen mit Schwere, Regel-ID und Business-Pfad.
Antwort (JSON): Die Antwort der API im Wortlaut.
Dokument: Das Erzeugte als Text, herunterladbar und als Eingangsdokument übernehmbar.
Vorschau: HTML oder PDF im Rahmen.
Verlauf: Jeder Aufruf mit Anfrage, Kopfzeilen und Antwort; aufklappbar und kopierbar. Dort steht die Begründung eines Fehlschlags auch dann noch, wenn das Ergebnisfeld längst den nächsten Aufruf zeigt.

„Als Eingangsdokument übernehmen“ schließt den Kreis: das Erzeugte wandert nach Feld 1 und lässt sich sofort validieren. Was der Dienst erzeugt, muss er auch für gültig erklären.

Wenn eine Operation nicht angeboten wird

Das ist eine Aussage über den Inhalt, nicht ein Mangel des Dienstes. Profile ohne Rechnungspositionen lassen sich prüfen und anzeigen, aber nicht in eine EN-16931-Rechnung überführen — es fehlt schlicht das, was gelesen werden müsste. Die Antwort sagt in diesem Fall genau das, und der Verlauf bewahrt sie auf.

Womit gemessen wird

Alle Urteile stammen aus den offiziellen Prüfwerkzeugen in genau diesen Fassungen. Die Konsole trifft keine eigene fachliche Entscheidung, und der Dienst ersetzt kein Ergebnis durch ein plausibles, wenn eine Engine ausfällt.