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",
  "container": "pdf",
  "syntax":   "CII",
  "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":  "XRechnung 3.0",
  "profile": "XRECHNUNG",
  "summary": "1 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-DE-17",
      "field":          "BT-3",
      "message":        "Mit dem Element \"Invoice type code\" (BT-3) sollen ausschließlich folgende Codes aus der Codeliste UNTDID 1001 übermittelt werden: 326, 380, 384, 389 …",
      "fix_suggestion": "Bei einer Vorschussrechnung (386) ist die Warnung hinnehmbar: XRechnung empfiehlt den Code nicht, lässt ihn aber zu. Wer sie vermeiden will, nimmt 326 (Teilrechnung).",
      "xpath":          "//rsm:ExchangedDocument/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 gültige 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). Unterstützt mehrere Positionen, die USt-Kategorien S, Z, E, AE, K und G, durchlaufende Posten, Rabatte und Zuschläge, Leistungsdatum oder Leistungszeitraum, schon gezahlte Beträge, Bezüge auf frühere Rechnungen, Anlagen sowie Überweisung oder SEPA-Lastschrift. Zustandslos: Wir speichern nichts, auch keine Anlagen. REST: POST /v1/create. 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"
}

xml kommt immer mit, außer über MCP bei einer ZUGFeRD-Rechnung mit Anlagen. Dann holt extract_xml es aus der PDF.

Anlagen

Anlagen stehen nur im XML der E-Rechnung (BT-125), nicht zusätzlich als Anhang der PDF. Jede Datei hat höchstens 5 MB, alle zusammen ebenfalls höchstens 5 MB, gemessen nach dem Dekodieren. Den Typ lesen wir an der Endung (.pdf, .png, .jpg, .jpeg, .csv, .xlsx, .ods) und prüfen ihn an den ersten Bytes der Datei; passen sie nicht zusammen, kommt 400. Ein Dateiname hat bis zu 100 Zeichen, ohne / und \ und ohne Punkt am Anfang; zwei Namen, die sich nur in Groß- und Kleinschreibung unterscheiden, gelten als gleich. description (BT-123) hat höchstens 200 Zeichen. In content_base64 steht reines Base64; einen Vorsatz data:…;base64, schneiden wir ab. Base64 macht die Dateien um ein Drittel größer: 5 MB Anlagen ergeben rund 7 MB im Aufruf, und die Antwort trägt sie noch einmal in der Rechnung. Über MCP schickst du deshalb besser nur kleine Anlagen.

Absenderprofil

Was im Aufruf fehlt, ergänzen wir aus dem Absenderprofil deines Kontos: den ganzen Verkäufer, wenn seller fehlt (die Steuernummer daraus nur, wenn das Profil keine USt-IdNr. hat), dazu IBAN, BIC, Kontoinhaber, Zahlungsbedingungen, Logo und bei einer Lastschrift die Gläubiger-ID. Was im Aufruf steht, gilt immer. Du pflegst das Profil im Konto unter „Absender“ oder über die API: GET /v1/keys/issuer liest es, PUT /v1/keys/issuer speichert es, DELETE /v1/keys/issuer löscht es. Felder: name, street, zip, city, country, vat_id, tax_number, email, phone, contact_name, iban, bic, account_name, payment_terms, logo_b64, creditor_id. PUT ändert nur die Felder, die im Aufruf stehen; eine leere Zeichenkette oder null löscht ein Feld. Eine USt-IdNr. ohne Ländercode, eine Steuernummer in falscher Form und eine ungültige Gläubiger-ID lehnt PUT mit 400 ab.

Fehler

Ungültige Eingaben beantworten wir mit 400 und { "error": "Ungültige Eingabe", "details": "…" }. Fehler im Schema nennen Pfad und Grund, mehrere durch Semikolon getrennt. Inhaltliche Probleme, etwa eine Lastschrift ohne Mandatsreferenz, stehen als ganze Sätze in details, mehrere durch Leerzeichen getrennt. Ein Datum, das nicht die Form YYYY-MM-DD hat, nennt sein Feld, etwa preceding_invoices[0].date (gezählt ab 0). Über MCP kommt bei inhaltlichen Problemen und beim Datum dasselbe Objekt als Ergebnis. Fehler im Schema meldet über MCP schon das Protokoll: Du bekommst einen Werkzeugfehler (isError: true) mit dem Text der Schemaprüfung, kein Objekt mit error und details.

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. In Automatisieren sind 20 Umwandlungen im Monat enthalten, in Skalieren 100, in Enterprise und im Testzugang so viele wie vereinbart. Darüber kostet jede weitere 3,99 € zzgl. USt mit accept_overage: true. Im Testzugang gibt es keine Mehrnutzung; ist das Kontingent aufgebraucht, antwortet /confirm mit 402 ohne overage_required. Ohne Tarif kostet jede 3,99 € zzgl. USt, bezahlt wird erst eine Datei, die die Prüfung bestanden hat. Ein vereinbartes Kontingent gilt auch im kostenlosen Tarif: Dann kommt die Datei sofort, wie mit Tarif. Ist es aufgebraucht, gibt es dort weder Mehrnutzung noch Einzelkauf: /confirm antwortet mit 402 ohne overage_required und ohne payment_required. 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 drei Minuten je Rechnung; mehrere lesen wir nacheinander. 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. Die Antwort kann länger dauern: Lass dein Programm bis zu drei Minuten warten. Mit Tarif kommt die fertige Datei als Base64 zurück, danach sind Upload und Entwurf gelöscht. Ohne Tarif erzeugen und prüfen wir sie ebenso, antworten aber mit 402 und payment_required: true; der Auftrag steht dann auf awaiting_payment.
5. Nur ohne Tarif: POST /v1/convert/{id}/checkout gibt die Adresse der Zahlung zurück. Nach der Zahlung holt GET /v1/convert/{id}/file die Datei.

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, awaiting_payment (erzeugt und geprüft, wartet auf die Zahlung; dazu payment: { price_cents, paid }), 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,
             "trial_until": null, "individual": false },
  "blocked_reason": null,
  "batch_limit": 20,
  "pays_per_conversion": false,
  "price_cents": 399,
  "seller": { "source": "billing_details", "name": "Holzbau Weber GmbH", "street": "Lindenweg 3",
              "postal_code": "72070", "city": "Tübingen", "country": "DE", "vat_id": "DE123456789",
              "tax_number": null, "profile_incomplete": false }
}

Gezählt wird je Kalendermonat, in einem Firmenkonto über die Firma. overage_possible sagt, ob du über das Kontingent hinaus mit accept_overage weiter umwandeln kannst; im Testzugang nie. trial_until ist der letzte Tag eines Testzugangs (YYYY-MM-DD), sonst null. individual ist true, wenn ein vereinbartes Kontingent statt dem des Tarifs gilt. batch_limit sagt, wie viele Dateien ein Aufruf tragen darf. pays_per_conversion ist true, wenn dein Konto keine Umwandlungen im Monat hat, weder im Tarif noch vereinbart; dann kostet jede price_cents. blocked_reason ist bei Sandbox-Keys gesetzt. seller sagt, welcher Absender gilt, bevor es einen Entwurf gibt: Mit source profile ist es dein vollständiges Absenderprofil, und der Entwurf fragt nicht nach ihm. Mit billing_details ist es die Rechnungsanschrift deines Kontos, mit ihr ist der Absender im Entwurf vorbelegt. Mit invoice lesen wir ihn aus der Rechnung, die Anschrift ist dann leer. tax_number ist die Steuernummer aus dem Absenderprofil; die Rechnungsanschrift kennt keine. profile_incomplete ist true, wenn es ein Absenderprofil gibt, dem Straße, PLZ oder Ort fehlen; es zählt erst, wenn es vollständig ist.

Entwurf: GET /v1/convert/{id}

Der Auftrag wie oben, im Status draft zusätzlich mit draft. Beträge in Euro, nicht in Cent. in_progress ist true, solange eine Bestätigung für ihn läuft. GET /v1/convert/{id}/pdf liefert die hochgeladene Rechnung als PDF, solange der Entwurf besteht; danach 404.

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. …"
}

Eine Bestätigung dauert meist nur Sekunden, kann aber länger dauern, denn wir erzeugen und prüfen die E-Rechnung dabei. Lass dein Programm bis zu drei Minuten auf die Antwort warten. Bricht die Verbindung vorher ab, schick dieselbe Bestätigung noch einmal: Wir zählen die Umwandlung und löschen Upload und Entwurf erst, wenn die Antwort hinausging. Doppelt zählt nichts. Kommt darauf 409 mit in_progress: true, läuft die erste Bestätigung noch. Warte ein paar Sekunden und frag mit GET /v1/convert/{id} den Stand ab. Steht dort in_progress: true, läuft sie noch, und du wartest weiter. Sonst gilt der Status: Bei draft schickst du die Bestätigung noch einmal, bei awaiting_payment geht es mit dem Kauf weiter. Bei done ist die Umwandlung fertig und gezählt; kam die Datei nicht bei dir an, schreib uns.

Ohne Tarif: kaufen und abholen

Ohne Tarif antwortet /confirm mit 402, sobald die Datei erzeugt ist und die Prüfung bestanden hat: { payment_required: true, price_cents: 399, prefill: { email, company, country, vat_id } }. Sie liegt dann bis zu 25 Stunden bereit.

Fehler

Ist eine Frist abgelaufen, löschen wir Auftrag und Datei, spätestens zehn Minuten danach. Bis dahin antwortet /confirm mit 410 und expired: true, ab dann jeder Aufruf mit 404, wie bei einem unbekannten Auftrag.

Stapel-Prüfung auf dem Server. Für viele Rechnungen auf einmal, ohne dass dein Programm oder Browser die ganze Zeit verbunden bleibt: Dateien hochladen, starten, später die Ergebnisse abholen. Ab Automatisieren. Die Rechnungen liegen verschlüsselt auf unserem Server in Deutschland, bis sie geprüft sind, und werden direkt danach gelöscht. Die Ergebnisse bleiben sieben Tage, danach löschen wir sie. Wenn alles fertig ist, kommt eine E-Mail an die Adresse des Kontos. In einem Firmenkonto kann der Inhaber das für die anderen Zugänge abschalten (PATCH /v1/org/settings mit { "stapel_ablage": false }).

Aufrufe

Jede Datei zählt aufs Wochenkontingent. Ist es aufgebraucht, hält der Auftrag an (status: "angehalten", grund: "kontingent"); die übrigen Dateien bleiben ungeprüft und werden gelöscht. Der Server prüft solche Aufträge nur auf Plätzen, die gerade frei sind; wer direkt prüft, geht vor.

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