API-Schnellreferenz

Alle Ausgabeformate auf einen Blick

Die XInvoice API unterstützt vier Ausgabeformate für E-Rechnungen. Diese Seite enthält lauffähige Beispiele für jedes Format sowie den Polling-Ablauf für asynchrone Anfragen.

Nur eine Rechnung prüfen?

Nutze den Web-Validator für schnelle Browser-Tests mit XML oder ZUGFeRD-PDF.

Zum Validator

E-Rechnungen automatisieren?

Nutze die API für wiederkehrende Validierung, Erzeugung und Abruf in deiner Software.

Zur Entwicklerseite

Übersicht der Formate

Das Ausgabeformat wird über den Parameter `document_format` im JSON-Body gesteuert. Das optionale Feld `document_profile` ist nur für ZUGFeRD relevant.

→ xrechnung_ubl – XRechnung 3.x UBL 2.1 XML (Standard, reines XML)
→ xrechnung_cii – XRechnung 3.x CII D16B XML (reines XML, B2G-tauglich)
→ zugferd + EN16931 – ZUGFeRD 2.x EN16931 Hybrid-PDF (B2B, kein Profil angeben = Default)
→ zugferd + XRECHNUNG – ZUGFeRD 2.x mit XRECHNUNG 3.0 Profil (B2G, PDF + CII)

1. XRechnung UBL erzeugen (Standard)

Das Standard-Format. Reines UBL-XML, für Behörden und B2B. Wird asynchron verarbeitet – die Antwort enthält eine `invoice_id` zum Polling.

curl -X POST https://api.xinvoice.net/v1/invoices/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_format": "xrechnung_ubl",
    "invoice_number": "RE-2026-001",
    "issue_date": "2026-04-01",
    "due_date": "2026-04-30",
    "buyer_reference": "04011000-12345-03",
    "currency": "EUR",
    "seller": {
      "name": "Muster GmbH",
      "vat_id": "DE123456789",
      "street": "Musterstraße 1",
      "postal_code": "10115",
      "city": "Berlin",
      "country_code": "DE",
      "email": "kontakt@muster.de"
    },
    "buyer": {
      "name": "Kunde GmbH",
      "street": "Hauptweg 5",
      "postal_code": "20095",
      "city": "Hamburg",
      "country_code": "DE"
    },
    "items": [
      {
        "name": "Beratungsleistung April",
        "quantity": 8,
        "unit_code": "HUR",
        "price": 150.00,
        "tax_rate": 19
      }
    ]
  }'

POST /v1/invoices – XRechnung UBL (asynchron)

2. XRechnung CII erzeugen (B2G-Alternative)

Identischer Payload wie UBL – nur `document_format` ändern. Das Ergebnis ist CII D16B XML mit XRECHNUNG 3.0 Profil. Wird von ZRE und OZG-RE akzeptiert.

curl -X POST https://api.xinvoice.net/v1/invoices/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_format": "xrechnung_cii",
    "invoice_number": "RE-2026-002",
    "issue_date": "2026-04-01",
    "due_date": "2026-04-30",
    "buyer_reference": "04011000-12345-03",
    "currency": "EUR",
    "seller": { "name": "Muster GmbH", "vat_id": "DE123456789",
                "street": "Musterstraße 1", "postal_code": "10115",
                "city": "Berlin", "country_code": "DE" },
    "buyer": { "name": "Bundesbehörde", "street": "Behördenweg 1",
               "postal_code": "10115", "city": "Berlin", "country_code": "DE" },
    "items": [{ "name": "IT-Dienstleistung", "quantity": 8,
                "unit_code": "HUR", "price": 150.00, "tax_rate": 19 }]
  }'

POST /v1/invoices – XRechnung CII (asynchron)

3. ZUGFeRD EN16931 erzeugen (B2B)

Hybrid-PDF mit eingebettetem CII-XML, EN16931 (Comfort) Profil. Für B2B empfohlen, da die Rechnung als normales PDF lesbar und gleichzeitig maschinenverarbeitbar ist.

curl -X POST https://api.xinvoice.net/v1/invoices/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_format": "zugferd",
    "invoice_number": "RE-2026-003",
    "issue_date": "2026-04-01",
    "due_date": "2026-04-30",
    "currency": "EUR",
    "seller": { "name": "Muster GmbH", "vat_id": "DE123456789",
                "street": "Musterstraße 1", "postal_code": "10115",
                "city": "Berlin", "country_code": "DE",
                "email": "kontakt@muster.de" },
    "buyer": { "name": "Kunde GmbH", "street": "Hauptweg 5",
               "postal_code": "20095", "city": "Hamburg", "country_code": "DE" },
    "items": [{ "name": "Beratungsleistung", "quantity": 5,
                "unit_code": "HUR", "price": 120.00, "tax_rate": 19 }]
  }'

POST /v1/invoices – ZUGFeRD EN16931 (Comfort)

4. ZUGFeRD XRECHNUNG erzeugen (B2G als Hybrid-PDF)

ZUGFeRD mit XRECHNUNG 3.0 Profil: behördentauglich als Hybrid-PDF. Das eingebettete CII-XML trägt den CustomizationID `urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0`.

curl -X POST https://api.xinvoice.net/v1/invoices/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_format": "zugferd",
    "document_profile": "XRECHNUNG",
    "invoice_number": "RE-2026-004",
    "issue_date": "2026-04-01",
    "due_date": "2026-04-30",
    "buyer_reference": "04011000-12345-03",
    "currency": "EUR",
    "seller": { "name": "Muster GmbH", "vat_id": "DE123456789",
                "street": "Musterstraße 1", "postal_code": "10115",
                "city": "Berlin", "country_code": "DE" },
    "buyer": { "name": "Bundesbehörde", "street": "Behördenweg 1",
               "postal_code": "10115", "city": "Berlin", "country_code": "DE" },
    "items": [{ "name": "IT-Dienstleistung", "quantity": 8,
                "unit_code": "HUR", "price": 150.00, "tax_rate": 19 }]
  }'

POST /v1/invoices – ZUGFeRD XRECHNUNG 3.0 (B2G Hybrid-PDF)

5. Ergebnis abholen (Polling)

Alle obigen Requests laufen asynchron und liefern sofort eine `invoice_id` zurück (Status `queued`). Das fertige Dokument wird per GET abgerufen:

# Schritt 1: Ergebnis-Status prüfen
curl https://api.xinvoice.net/v1/invoices/{INVOICE_ID} \
  -H "Authorization: Bearer YOUR_API_KEY"

Falls die Rechung fertig ist, wird sie gleich zurückgegeben.

# Schritt 2: Wenn status = "generated", PDF herunterladen (nur bei ZUGFeRD)
curl https://api.xinvoice.net/v1/invoices/{INVOICE_ID}/download-pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output rechnung.pdf

Oder:
Im Schritt 1 gleich den URL-Parameter ?include_pdf_data=1 anhängen. 
Dann enthält der JSON-Response aus Schritt 1 bereits die PDF-Datei 
als base64-encoded String.

# Alternativ: synchrone Erzeugung (wartet auf Ergebnis)
# Der synchrone Modus schließt include_pdf_data=1 implizit mit ein.
curl -X POST https://api.xinvoice.net/v1/invoices/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-sync" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Polling und synchrone Alternative (Prefer: respond-sync)

6. Validierung – XML oder PDF

Eine bestehende E-Rechnung validieren – als Raw-XML, als JSON-Payload oder als ZUGFeRD-PDF. Die Antwort enthält `valid` mit dem Wert true oder false sowie strukturierte Fehlermeldungen mit Business-Rule-Referenz.

# XRechnung UBL oder CII XML validieren (Raw)
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

# ZUGFeRD PDF validieren (Raw)
curl -X POST https://api.xinvoice.net/v1/invoices/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @rechnung.pdf

# JSON-Payload validieren (wie beim Erzeugen, aber keine Speicherung)
curl -X POST https://api.xinvoice.net/v1/invoices/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "document_format": "xrechnung_ubl", "invoice_number": "RE-2026-001", ... }'

POST /v1/invoices/validate – XML, PDF oder JSON