XRechnung per API erzeugen: Anleitung mit Codebeispielen

Wie Sie aus Rechnungsdaten per API eine gültige XRechnung erzeugen: Format, Pflichtangaben, Prüfbericht und Zustellung – mit curl- und SDK-Beispielen.

Stand: 29. Oktober 2026. Dieser Ratgeber ersetzt keine Steuerberatung.

Kurz beantwortet

Eine XRechnung ist eine E-Rechnung nach der europäischen Norm EN 16931 mit den deutschen Zusatzregeln (CIUS), übertragen als XML-Datei in der Syntax UBL oder CII. An öffentliche Auftraggeber ist sie schon heute der Standard; zwischen Unternehmen müssen Sie ab 2027 E-Rechnungen ausstellen, wenn Ihr Vorjahresumsatz über 800.000 Euro lag, ab 2028 ohne Umsatzgrenze. Eine API nimmt Ihre Rechnungsdaten als JSON entgegen und liefert eine geprüfte XRechnung zurück, ohne dass Sie das Regelwerk selbst nachbauen.

Was eine XRechnung technisch ist

Eine XRechnung ist reines XML. Die EN 16931 beschreibt die Inhalte als nummerierte Geschäftsbegriffe (BT-1 bis BT-165, Gruppen BG-1 bis BG-32) und erlaubt zwei Syntaxen: UBL 2.1 und UN/CEFACT CII. Beide sind gleichwertig; viele Empfänger nehmen beide an.

Die KoSIT ergänzt die Norm um deutsche Geschäftsregeln mit Kennungen wie BR-DE-15, etwa Pflicht zur Käuferreferenz oder zu Kontaktdaten des Verkäufers. Geprüft wird mit dem offenen KoSIT-Validator und der dazu veröffentlichten Prüfkonfiguration: zuerst das XML-Schema, dann die Schematron-Regeln der Norm und der XRechnung.

Versionen: Seit 1. Februar 2024 gilt XRechnung 3.0; sie bleibt nach Angabe der KoSIT mindestens bis 31. Juli 2027 in Kraft. Version 4.0 liegt als vorläufige Spezifikation vor. Statt eines Sommer- und eines Winter-Releases plant die KoSIT mittelfristig ein Haupt-Release pro Jahr; dazwischen erscheinen Fehlerbehebungen der Prüfkonfiguration. Fakturnaut prüft derzeit gegen XRechnung 3.0.2 mit der Prüfkonfiguration vom 31. August 2026.

ZUGFeRD (in Frankreich Factur-X) ist ein hybrides Format: ein PDF/A-3, in das die Rechnungsdaten als CII-XML eingebettet sind. Im Profil EN 16931 erfüllt es dieselbe Norm, ist aber zusätzlich für Menschen lesbar.

Mehr dazu im Ratgeber XRechnung oder ZUGFeRD?

Pflichtangaben, an denen es meist scheitert

Die folgenden Regeln stammen aus der Prüfkonfiguration, die wir einsetzen (XRechnung 3.0.2). Jede ist ein Fehler, der die Rechnung ungültig macht:

• Käuferreferenz (BT-10), BR-DE-15: muss immer angegeben werden. An Behörden ist das die Leitweg-ID; unter Unternehmen genügt eine Bestellnummer oder ein Platzhalter.
• Kontakt des Verkäufers (BG-6), BR-DE-2, BR-DE-5 bis BR-DE-7: Name, Telefonnummer (BT-42) und E-Mail-Adresse (BT-43) des Ansprechpartners.
• Zahlungsanweisungen (BG-16), BR-DE-1: Zahlungsart und bei Überweisung die Kontodaten (BG-17, BR-DE-23-a).
• Umsatzsteuer: Jede Steuerkategorie braucht einen Steuersatz (BT-119, BR-DE-14). Steuerbefreite Umsätze, Reverse Charge oder innergemeinschaftliche Lieferungen brauchen einen Befreiungsgrund als Text (BT-120) oder Code (BT-121), zum Beispiel BR-E-10 oder BR-AE-10. Bei steuerpflichtigen und den meisten anderen Steuerkategorien braucht der Verkäufer eine USt-IdNr. (BT-31) oder Steuernummer (BT-32), oder es ist ein Steuervertreter angegeben (BR-DE-16).
• Elektronische Adressen (BT-34, BT-49): Verkäufer und Käufer brauchen je eine elektronische Adresse mit Schema, etwa EM für E-Mail oder 0204 für eine Leitweg-ID (PEPPOL-EN16931-R020 und -R010).

Das Leistungsdatum (BT-72) oder ein Leistungszeitraum fehlt oft ebenfalls. Die XRechnung meldet das nur als Hinweis; umsatzsteuerlich ist der Zeitpunkt der Leistung aber eine Pflichtangabe der Rechnung (§ 14 Abs. 4 Satz 1 Nr. 6 UStG).

Selbst bauen oder API nutzen

Sie können eine XRechnung selbst erzeugen. Es gibt gute Open-Source-Bibliotheken, zum Beispiel Mustangproject für Java, ZUGFeRD-csharp für .NET oder horstoeko/zugferd für PHP, und den KoSIT-Validator zum Prüfen.

Mit der Bibliothek ist das XML geschrieben. Was danach bleibt:

• Prüfen: den Validator mit der passenden Prüfkonfiguration betreiben und seine Meldungen in verständliche Fehler für Ihre Nutzer übersetzen.
• Rechnen: Summen, Steueraufschlüsselung und Rundung nach EN 16931, damit die Regeln BR-CO-* nicht anschlagen.
• Aktualisieren: jedes neue Release der KoSIT einspielen und testen.
• Zustellen: für Peppol einen Vertrag mit einem zertifizierten Zugangspunkt.
• Aufbewahren: jede Rechnung unverändert und auffindbar archivieren (§ 14b UStG).

Lohnt sich das? Wenn E-Rechnungen Ihr Kerngeschäft sind oder Sie nur ein Format für wenige Rechnungen brauchen, kann eine Bibliothek reichen. Wenn Sie Rechnungen für viele Kunden erzeugen und sich auf Ihr eigenes Produkt konzentrieren wollen, nimmt Ihnen eine API die laufende Pflege ab. Was die Fakturnaut-API kann, zeigt der Überblick für Softwarehersteller; was sie kostet, steht unter API-Preise.

Schritt für Schritt mit der Fakturnaut-API

Alle Beispiele laufen in der kostenlosen Sandbox: Testrechnungen sind gültige XRechnungen, als Test gekennzeichnet, werden nie berechnet und nach 30 Tagen gelöscht. Jeder Build prüft die Beispiele gegen die API-Referenz; Anfrage, Antwort und Prüfbericht prüfen wir zusätzlich in der Sandbox.

1. Konto anlegen und Testschlüssel kopieren

Registrieren Sie sich und legen Sie im Portal unter Verkäufer das Unternehmen an, das die Rechnungen ausstellt – im Beispiel die Muster GmbH – mit Anschrift, USt-IdNr., Ansprechpartner mit Telefon und E-Mail sowie Bankverbindung. Diese Angaben kommen aus dem Verkäufer in jede Rechnung. Erstellen Sie dann unter API-Schlüssel einen Testschlüssel; er beginnt mit fkn_test_ und wird nur einmal angezeigt.

2. Rechnungsdaten als JSON senden

Die Muster GmbH berechnet der Stadt Beispielhausen zwei Schulungstage. Die Leitweg-ID 04011000-BEISPIEL-19 ist ein erfundenes Beispiel; die echte nennt Ihnen die Behörde.

export FAKTURNAUT_KEY=fkn_test_…   # Ihr Testschlüssel
# sellerId: die ID Ihres Verkäufers aus dem Portal
cat > invoice.json <<'JSON'
{
  "sellerId": "5b1d7f0e-3c2a-4e8b-9f61-2d4c8a7e9b03",
  "number": "RE-2026-0107",
  "issueDate": "2026-11-03",
  "dueDate": "2026-12-03",
  "deliveryDate": "2026-10-28",
  "buyerReference": "04011000-BEISPIEL-19",
  "buyer": {
    "name": "Stadt Beispielhausen",
    "electronicAddress": "04011000-BEISPIEL-19",
    "electronicAddressScheme": "0204",
    "address": {
      "street": "Rathausplatz 1",
      "city": "Beispielhausen",
      "postCode": "99999",
      "country": "DE"
    }
  },
  "lines": [
    { "name": "Schulung Fachverfahren", "quantity": 2, "unitCode": "DAY", "netPrice": 850.0, "vatRate": 19 }
  ]
}
JSON
curl -X POST https://api.fakturnaut.com/v1/invoices \
  -H "Authorization: Bearer $FAKTURNAUT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data @invoice.json

Der Idempotency-Key macht Wiederholungen sicher: Senden Sie dieselbe Anfrage nach einem Netzwerkfehler mit demselben Schlüssel erneut, entsteht keine zweite Rechnung. Die Antwort (gekürzt):

{
  "id": "8f3a2c71-5d04-4e9b-b6a1-3c7e9d2f0b58",
  "number": "RE-2026-0107",
  "typeCode": "380",
  "amountDue": 2023.0,
  "currency": "EUR",
  "findings": [],
  "documents": [
    {
      "format": "xrechnung-ubl",
      "mediaType": "application/xml",
      "href": "/v1/invoices/8f3a2c71-5d04-4e9b-b6a1-3c7e9d2f0b58/document?format=xrechnung-ubl"
    },
    {
      "format": "zugferd",
      "mediaType": "application/pdf",
      "href": "/v1/invoices/8f3a2c71-5d04-4e9b-b6a1-3c7e9d2f0b58/document?format=zugferd"
    }
  ]
}

Dasselbe mit dem TypeScript-SDK (npm install @fakturnaut/sdk); SDKs für PHP, Java und C# nennt die Dokumentation:

import { readFileSync } from 'node:fs';
import { Configuration, InvoiceRequestFromJSON, InvoicesApi } from '@fakturnaut/sdk';
import { newIdempotencyKey } from '@fakturnaut/sdk/helpers';

const invoices = new InvoicesApi(new Configuration({ accessToken: process.env.FAKTURNAUT_KEY }));
const issued = await invoices.issueInvoice({
  idempotencyKey: newIdempotencyKey(), // bei einer Wiederholung denselben Schlüssel verwenden
  invoiceRequest: InvoiceRequestFromJSON(JSON.parse(readFileSync('invoice.json', 'utf8'))),
});
console.log(issued.number, issued.documents);

3. Prüfbericht lesen

Mit POST /v1/invoices/validate prüfen Sie dieselben Daten, ohne etwas auszustellen. Fehlt zum Beispiel die Leitweg-ID, antwortet die API so:

{
  "valid": false,
  "summary": {
    "de": "Die E-Rechnung ist nicht gültig: 1 Fehler.",
    "en": "The e-invoice is not valid: 1 error."
  },
  "totals": {
    "taxExclusiveAmount": 1700.0,
    "vatTotal": 323.0,
    "amountDue": 2023.0
  },
  "findings": [
    {
      "ruleId": "BR-DE-15",
      "severity": "ERROR",
      "source": "BUSINESS_RULES",
      "location": "BT-10",
      "message": {
        "de": "Für XRechnung muss die Käuferreferenz bzw. Leitweg-ID (BT-10) angegeben werden.",
        "en": "XRechnung requires the buyer reference or Leitweg-ID (BT-10)."
      }
    }
  ]
}

ruleId nennt die verletzte Regel, location das Feld (hier BT-10, im JSON buyerReference), message die Erklärung auf Deutsch und Englisch. Zeigen Sie message Ihren Nutzern an und werten Sie ruleId im Code aus. Die Lösung hier: buyerReference mit der Leitweg-ID ergänzen. Beim Ausstellen führt derselbe Fehler zur Antwort 422 mit dem Code invoice.invalid und denselben findings; eine ungültige Rechnung wird nie ausgestellt. Alle Codes erklärt Fehler und Regelcodes.

4. XML und PDF abrufen

Jedes Dokument in documents laden Sie über seinen href. Das XML ist die XRechnung, das PDF die ZUGFeRD-Fassung derselben Rechnung:

curl -OJ "https://api.fakturnaut.com/v1/invoices/<id>/document?format=xrechnung-ubl" \
  -H "Authorization: Bearer $FAKTURNAUT_KEY"
curl -OJ "https://api.fakturnaut.com/v1/invoices/<id>/document?format=zugferd" \
  -H "Authorization: Bearer $FAKTURNAUT_KEY"

Die Dokumente bleiben unverändert gespeichert; das ETag ist ihre SHA-256-Prüfsumme. Sie können sie auch selbst in unserer kostenlosen Prüfung gegenprüfen.

5. Zustellen

Peppol ist ein europäisches Netz für E-Rechnungen: Sender und Empfänger sind über zertifizierte Zugangspunkte verbunden, adressiert wird mit Schema und Kennung. Peppol lohnt sich, wenn Ihr Empfänger dort erreichbar ist – die Rechnungseingangsplattform des Bundes zum Beispiel ist es – und wenn Sie viele Rechnungen automatisch und mit Zustellstatus versenden. Ohne recipient nimmt die API die elektronische Adresse des Käufers aus der Rechnung (BT-49):

curl -X POST https://api.fakturnaut.com/v1/invoices/<id>/deliveries \
  -H "Authorization: Bearer $FAKTURNAUT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{"channel": "peppol", "recipient": "0204:04011000-BEISPIEL-19"}'

In der Sandbox ist Peppol simuliert; den Status verfolgen Sie mit GET /v1/deliveries/{id} oder per Webhook. Echte Peppol-Zustellung braucht einen verifizierten Verkäufer mit Peppol-Adresse (zum Beispiel Schema 9930 mit der USt-IdNr.). Details: Zustellungen und Status.

Zustellung: Über Peppol in den Tarifen Growth, Scale und Enterprise. Versand per E-Mail: in Vorbereitung.

XRechnung an Behörden zustellen

Für Rechnungen an die Bundesverwaltung gilt die E-Rechnungsverordnung (E-RechV): Die Leitweg-ID gehört in die Käuferreferenz (BT-10), dazu Bankverbindung, Zahlungsbedingungen und die E-Mail-Adresse des Rechnungsstellers (§ 5 Abs. 1 E-RechV). Hat die Behörde Ihnen bei der Beauftragung eine Bestellnummer (BT-13) oder eine Lieferantennummer (BT-29) mitgeteilt, gehören auch diese in die Rechnung (§ 5 Abs. 2 E-RechV). Eingereicht wird über die Rechnungseingangsplattform des Bundes (OZG-RE): per Weberfassung, Upload, E-Mail oder Peppol. Über Peppol ist die Empfängerkennung 0204: plus Leitweg-ID. Länder und Kommunen betreiben teils eigene Portale mit eigenen Vorgaben.

Was Fakturnaut übernimmt: Es erzeugt die XRechnung mit der Leitweg-ID, prüft sie gegen die Regeln der KoSIT, bevor sie ausgestellt wird, und stellt sie über Peppol an 0204:<Leitweg-ID> zu.

Was Sie als Rechnungssteller selbst erledigen:

• die Leitweg-ID bei der Behörde erfragen (Auftrag, Vertrag oder Ansprechpartner),
• sich einmalig und kostenlos an der OZG-RE registrieren – das verlangt das Portal auch für Peppol,
• bei Ländern und Kommunen den Eingangsweg der jeweiligen Stelle klären,
• eine Zurückweisung durch das Portal beachten und die Rechnung korrigiert neu einreichen.

Mehr zur Leitweg-ID im Ratgeber Leitweg-ID: Rechnungen an Behörden.

Gutschriften als XRechnung

Stellt Ihr Kunde die Rechnung für Ihre Leistung aus (Gutschrift im Sinne des § 14 Abs. 2 Satz 5 UStG, Rechnungstyp 389), ist auch das eine E-Rechnung und folgt denselben Regeln. Mehr dazu im Ratgeber Gutschrift als E-Rechnung.

Gutschriften (Self-Billing): in Vorbereitung. Zugang auf Anfrage: Schreiben Sie uns.

Häufige Fragen

Brauche ich für eine XRechnung eine Leitweg-ID?

Nur an öffentliche Auftraggeber. Die XRechnung verlangt zwar immer eine Käuferreferenz (BT-10), an Unternehmen genügt aber eine Bestellnummer oder ein Platzhalter wie „-“.

UBL oder CII – welche Syntax soll ich erzeugen?

Beide sind nach EN 16931 gleichwertig. Wenn Ihr Empfänger nichts vorgibt, ist UBL für Peppol verbreitet. Die Fakturnaut-API erzeugt beide Syntaxen aus denselben Daten.

Ist ein PDF mit eingebettetem XML eine XRechnung?

Nein. Das ist ZUGFeRD. Im Profil EN 16931 ist ZUGFeRD ebenfalls eine E-Rechnung im Sinne des Umsatzsteuergesetzes, aber keine XRechnung. Viele Behördenportale verlangen XRechnung.

Was passiert bei einem neuen XRechnung-Release?

Die KoSIT veröffentlicht neue Versionen und Prüfkonfigurationen; der Bund kündigt Änderungen im Bundesanzeiger an. Fakturnaut übernimmt sie in den Prüfungen; Ihre Schnittstelle bleibt gleich, weil sie im Pfad versioniert ist (/v1).

Kann ich die API kostenlos testen?

Ja. In der Sandbox erzeugen Sie mit einem Testschlüssel gültige, als Test gekennzeichnete XRechnungen ohne Kosten und ohne Vertrag. Testdaten werden nach 30 Tagen gelöscht.

Ab wann müssen Unternehmen E-Rechnungen ausstellen?

Ab 1. Januar 2027, wenn der Gesamtumsatz im Vorjahr über 800.000 Euro lag, sonst ab 1. Januar 2028 (§ 27 Abs. 38 UStG). Empfangen können müssen Unternehmen E-Rechnungen schon seit 2025.

Quellen

• § 14 UStG, § 14b UStG und § 27 Abs. 38 UStG
• E-Rechnungsverordnung des Bundes: § 5
• BMF-Schreiben vom 15. Oktober 2025 und vom 15. Oktober 2026
• Fragen und Antworten zur E-Rechnung (Bundesfinanzministerium)
• XRechnung und Versionen und Bundles (KoSIT)
• Prüfkonfiguration XRechnung (KoSIT)
• Übertragung per Peppol und Übertragungskanäle (e-rechnung-bund.de)
• Die europäische Norm EN 16931 (Europäische Kommission, Englisch)
• ZUGFeRD (FeRD)

Stand: 29. Oktober 2026. Dieser Ratgeber ersetzt keine Steuerberatung.