ZUGFeRD / XRechnung
MCP Validation Server

Validiert eine E-Rechnung (ZUGFeRD/Factur-X PDF oder XRechnung XML) gegen EN 16931 und die deutschen Erweiterungen. Gibt strukturierte Fehler, Warnungen und Korrekturvorschläge zurück.

Input-Schema

Output-Schema

{
  "valid":    true,
  "format":   "ZUGFeRD 2.x",
  "profile":  "EN16931",
  "summary":  "Keine Probleme gefunden",
  "errors":   [],
  "warnings": [],
  "notices":  [],
  "metadata": {
    "invoice_number": "RE-2026-001",
    "issue_date":     "2026-04-01",
    "seller":         "Musterfirma GmbH",
    "buyer":          "Beispiel AG",
    "total_amount":   "1190.00",
    "currency":       "EUR"
  }
}

{
  "valid":   false,
  "format":  "ZUGFeRD 2.x",
  "profile": "EN16931",
  "summary": "2 Fehler, 1 Warnung gefunden",
  "errors": [
    {
      "severity":       "error",
      "rule_id":        "BR-DE-15",
      "field":          "BT-10",
      "message":        "Die Käuferreferenz / Leitweg-ID (BT-10) muss übermittelt werden.",
      "fix_suggestion": "Füge die Käuferreferenz / Leitweg-ID (BT-10) in 'ram:ApplicableHeaderTradeAgreement/ram:BuyerReference' ein.",
      "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
    }
  ],
  "warnings": [
    {
      "severity":       "warning",
      "rule_id":        "BR-CL-10",
      "field":          "BT-81",
      "message":        "Zahlungsmittelcode muss aus UNTDID 4461 stammen.",
      "fix_suggestion": "Verwende z.B. '58' für SEPA-Überweisung oder '59' für SEPA-Lastschrift.",
      "xpath":          "//ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode"
    }
  ]
}

Ausgabefelder

Extrahiert das eingebettete XML-Dokument aus einer ZUGFeRD/Factur-X-PDF. Gibt den vollständigen XML-Inhalt als String zurück, zusammen mit erkanntem Format und Profil.

Input

Output

{
  "xml_content": "<?xml version='1.0' encoding='UTF-8'?>\n<rsm:CrossIndustryInvoice ...>...</rsm:CrossIndustryInvoice>",
  "format":      "ZUGFeRD 2.x",
  "profile":     "EN16931"
}

Prüft, ob die für Menschen sichtbaren Daten im PDF (Rechnungsnummer, Datum, Gesamtbetrag) mit den im XML-Anhang gespeicherten Maschinendaten übereinstimmen. Deckt Manipulationen oder Erfassungsfehler auf.

Input

Output

{
  "consistent":    true,
  "discrepancies": []
}

{
  "consistent":    false,
  "discrepancies": [
    {
      "field":     "total_amount",
      "pdf_value": "1190.00",
      "xml_value": "1180.00",
      "message":   "Gesamtbetrag im PDF ('1190.00') unterscheidet sich von dem im XML ('1180.00')."
    }
  ]
}

Geprüfte Felder & Toleranzen

Erzeugt aus strukturierten Daten eine valide E-Rechnung — wahlweise als ZUGFeRD-PDF (PDF/A-3 mit eingebettetem EN-16931-CII-XML) oder als reine XRechnung-XML (CII mit XRechnung-3.0-CIUS und Leitweg-ID für B2G). Mehrere Positionen, alle USt-Kategorien (S/Z/E/AE), Rabatte/Zuschläge, Zahlungsangaben. REST: POST /v1/create. Stateless — es wird nichts gespeichert. Beträge in Cent, Datum als YYYY-MM-DD.

Input (Auszug)

Output

{
  "format":     "zugferd",
  "profile":    "EN16931",
  "pdf_base64": "JVBERi0xLjc…",
  "xml":        "<?xml version=\"1.0\"…",
  "branding":   "free_footer"
}

Macht aus einer bestehenden Rechnung als PDF, Word oder Excel eine E-Rechnung: ZUGFeRD in deinem bisherigen Layout oder XRechnung. Ein Sprachmodell auf unserem eigenen Server liest die Werte aus, wir rechnen sie nach und legen sie als Entwurf vor. Die E-Rechnung entsteht erst, wenn du den Entwurf bestätigst, und kommt nur zurück, wenn sie unsere Prüfung gegen EN 16931 besteht. Ab Automatisieren (20 Umwandlungen im Monat) und Skalieren (100). Umwandlungen zählen nicht auf das Prüf- oder Erstellkontingent.

Ablauf

1. POST /v1/convert mit einer oder mehreren Dateien. Antwort sofort mit 202 und je Datei einem Auftrag im Status queued.
2. GET /v1/convert/{id} abfragen, bis der Status draft ist, meist nach ein bis zwei Minuten. Bei mehreren Dateien oder längerer Erkennung kommt zusätzlich eine E-Mail an die Adresse des Kontos.
3. Den Entwurf prüfen. Was in uncertain steht, sollte ein Mensch ansehen; reasons sagt je Feld, warum.
4. POST /v1/convert/{id}/confirm mit den bestätigten Werten. Antwort mit der fertigen Datei als Base64. Danach sind Upload und Entwurf gelöscht.

Voraussetzungen

Hochladen: POST /v1/convert

{
  "batch": "lomvuvzjtl5y94syeglx",
  "jobs": [
    { "id": "5113py49uqxfatik47rn", "filename": "RE-2026-121.pdf", "format": "pdf",
      "status": "queued", "reason": null,
      "created_at": "2026-10-12T11:17:58.000Z", "expires_at": "2026-10-13T11:17:58.000Z" }
  ],
  "note": "Sobald ein Entwurf zur Prüfung bereitliegt, hat er den Status „draft“. …"
}

Status eines Auftrags: queued, processing, draft, done, rejected (Datei nicht umwandelbar, Grund in reason), failed. batch ist bei einer einzelnen Datei null.

Aufträge und Kontingent: GET /v1/convert

{
  "jobs": [ … ],
  "quota": { "limit": 20, "used": 11, "overage_cents": 399, "overage_possible": true },
  "blocked_reason": null
}

Gezählt wird je Kalendermonat, in einem Firmenkonto über die Firma. blocked_reason ist gesetzt, wenn der Tarif das Umwandeln nicht enthält.

Entwurf: GET /v1/convert/{id}

Der Auftrag wie oben, im Status draft zusätzlich mit draft. Beträge in Euro, nicht in Cent. GET /v1/convert/{id}/pdf liefert die hochgeladene Rechnung als PDF, solange der Entwurf besteht.

Bestätigen: POST /v1/convert/{id}/confirm

{
  "ok":       true,
  "filename": "RE-2026-121.pdf",
  "mime":     "application/pdf",
  "content":  "JVBERi0xLjc…",
  "note":     "Die E-Rechnung ist formal gültig und von dir bestätigt. …"
}

Fehler

Listet die Rechnungen, die wir dir gestellt haben, mit Nummer, Datum und Beträgen. GET /v1/invoices/{nummer}/pdf liefert das Dokument als PDF. Die Rechnungen sind selbst gültige E-Rechnungen im ZUGFeRD-Format nach EN 16931, deine Buchhaltung kann sie also einlesen. Dieselbe Liste steht im Konto unter „Rechnungen". Der Aufruf kostet kein Kontingent.

Anmeldung

Beispiel

curl -H "X-Api-Key: dein_key" https://api.zugferd-validator.de/v1/invoices

curl -H "X-Api-Key: dein_key" \
  -o ZF-2026-007.pdf \
  https://api.zugferd-validator.de/v1/invoices/ZF-2026-007/pdf

Antwort

{
  "invoices": [
    { "number": "ZF-2026-007", "date": "2026-08-17T09:12:03.000Z",
      "net": 2000, "vat": 380, "gross": 2380, "currency": "eur" }
  ]
}

Beträge in Cent. Es werden nur eigene Rechnungen ausgeliefert; die Nummer eines anderen Kontos beantworten wir mit 404.

Liefert das Prüfergebnis als Validierungsbericht im Format PDF/A-3b, zum Ablegen und Weitergeben. Der Bericht nennt das Ergebnis, alle Meldungen mit Regel-ID und Feld, den Prüfzeitpunkt, das erkannte Format samt Profil, die SHA-256-Prüfsumme der geprüften Datei und den Regelstand, also die Versionen der eingesetzten Prüfwerkzeuge. Jeder Aufruf prüft die Datei neu und zählt wie eine Validierung gegen das Wochenkontingent. Als MCP-Werkzeug validation_report und über REST als POST /v1/report.

Input

Output

Content-Type: application/pdf
Content-Disposition: attachment; filename="validierungsbericht-rechnung.pdf"
X-Validation-Result: valid | invalid

Beispiel

curl -X POST https://api.zugferd-validator.de/v1/report \
  -H "X-Api-Key: $ZV_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_content\": \"$(base64 -w0 rechnung.pdf)\", \"file_type\": \"pdf\", \"attach_source\": true}" \
  -o bericht.pdf