ZUGFeRD & XRechnung
Validation API (REST + MCP)

Validates an e-invoice (ZUGFeRD/Factur-X PDF or XRechnung XML) against EN 16931 and the German extensions. Returns structured errors, warnings and fix suggestions.

Input schema

Output schema

{
  "valid":    true,
  "format":   "ZUGFeRD 2.x",
  "profile":  "EN16931",
  "container": "pdf",
  "syntax":   "CII",
  "summary":  "No issues found",
  "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 error, 1 warning found",
  "errors": [
    {
      "severity":       "error",
      "rule_id":        "BR-DE-15",
      "field":          "BT-10",
      "message":        "The buyer reference / routing ID (BT-10) must be provided.",
      "fix_suggestion": "Add the buyer reference / routing ID (BT-10) in 'ram:ApplicableHeaderTradeAgreement/ram:BuyerReference'.",
      "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
    }
  ],
  "warnings": [
    {
      "severity":       "warning",
      "rule_id":        "BR-DE-17",
      "field":          "BT-3",
      "message":        "The element \"Invoice type code\" (BT-3) should carry only the following codes from code list UNTDID 1001: 326, 380, 384, 389 …",
      "fix_suggestion": "On a prepayment invoice (386) the warning is acceptable: XRechnung does not recommend the code, but it allows it. To avoid the warning, use 326 (partial invoice).",
      "xpath":          "//rsm:ExchangedDocument/ram:TypeCode"
    }
  ]
}

Output fields

Extracts the embedded XML document from a ZUGFeRD/Factur-X PDF. Returns the full XML content as a string, together with the detected format and profile.

Input

Output

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

Checks whether the human-readable data in the PDF (invoice number, date, total amount) matches the machine data stored in the XML attachment. Reveals tampering or data-entry errors.

Input

Output

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

{
  "consistent":    false,
  "discrepancies": [
    {
      "field":     "total_amount",
      "pdf_value": "1190.00",
      "xml_value": "1180.00",
      "message":   "The total amount in the PDF ('1190.00') differs from the one in the XML ('1180.00')."
    }
  ]
}

Checked fields & tolerances

Builds a valid e-invoice from structured data, either as a ZUGFeRD PDF (PDF/A-3 with embedded EN 16931 CII XML) or as plain XRechnung XML (CII with the XRechnung 3.0 CIUS and routing ID for B2G). Multiple line items, VAT categories S, Z, E, AE, K and G, disbursements without VAT, allowances and charges, delivery date or service period, amounts already paid, references to earlier invoices, attachments, and payment by transfer or SEPA direct debit. Stateless: nothing is stored, attachments included. REST: POST /v1/create. Amounts in cents, date as YYYY-MM-DD.

Input (excerpt)

Output

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

xml always comes along, except via MCP for a ZUGFeRD invoice with attachments. Then extract_xml gets it from the PDF.

Attachments

Attachments sit only in the XML of the e-invoice (BT-125), not as an extra attachment of the PDF. Each file may have at most 5 MB, and all together at most 5 MB as well, measured after decoding. We take the type from the extension (.pdf, .png, .jpg, .jpeg, .csv, .xlsx, .ods) and check it against the first bytes of the file; if they do not match, you get 400. A file name has up to 100 characters, without / and \ and without a leading dot; two names that differ only in upper and lower case count as the same. description (BT-123) has at most 200 characters. content_base64 holds plain Base64; we cut off a data:…;base64, prefix. Base64 makes files a third larger: 5 MB of attachments become about 7 MB in the request, and the response carries them again inside the invoice. Via MCP, better send only small attachments.

Sender profile

What the request leaves out, we fill in from the sender profile of your account: the whole seller if seller is missing (its tax number only if the profile has no VAT ID), plus IBAN, BIC, account holder, payment terms, logo and, for a direct debit, the creditor ID. What the request contains always wins. You maintain the profile in your account or via the API: GET /v1/keys/issuer reads it, PUT /v1/keys/issuer saves it, DELETE /v1/keys/issuer removes it. Fields: name, street, zip, city, country, vat_id, tax_number, email, phone, contact_name, iban, bic, account_name, payment_terms, logo_b64, creditor_id. PUT changes only the fields in the request; an empty string or null clears a field. PUT rejects a VAT ID without country code, a tax number in the wrong form and an invalid creditor ID with 400.

Errors

We answer invalid input with 400 and { "error": "Ungültige Eingabe", "details": "…" }. Schema errors name path and reason, several separated by semicolons. Problems with the content, such as a direct debit without mandate reference, come as whole sentences in details (in German), several separated by spaces. A date not in the form YYYY-MM-DD names its field, for example preceding_invoices[0].date (counted from 0). Via MCP, problems with the content and dates come back as the same object. Schema errors are caught earlier by the MCP protocol itself: you get a tool error (isError: true) with the text of the schema check, not an object with error and details.

Show an invoice in readable form. Turns an XRechnung (UBL or CII), a CII invoice or a ZUGFeRD/Factur-X PDF into a readable view. It is based on the KoSIT visualisation (Apache 2.0) in the version that comes with Mustang 2.26.0. No key needed; it does not count against the check quota but has its own daily limit: 20 per IP address without an account, 50 on the free plan, 500 on Automate, 2,000 on Scale (otherwise 429). Nothing is stored or logged. As an MCP tool: view_invoice.

Fields

Response: readable, html, format, profile, syntax, attachments (name, type, size, Base64), check (valid, number of errors and warnings, first messages) and limit. The HTML is cleaned: no script, no event handlers, no links with a target, no images or forms, plus a Content Security Policy. Still show it only in an <iframe sandbox> without rights, and save attachments as files instead of opening them in the browser. If the file cannot be shown, readable is false and check says why; a PDF without an e-invoice gives 422.

Check a Leitweg-ID. Checks structure, code (state 01 to 16, federal 99) and check digits (modulo 97-10) according to the KoSIT format specification 2.0.2. If the check digits are wrong or missing, the response gives the matching ID in corrected_id. It does not say whether the ID is assigned; there is no public directory. No key needed, no quota, at most 120 calls per minute (else 429). Nothing is stored. As MCP tool: check_leitweg_id.

Fields

Response (200, also for an invalid ID): valid, leitweg_id (normalised), parts (coarse, fine, check_digits), region, expected_check_digits, corrected_id, errors and warnings (each code and message), notice. Have a suggested ID confirmed by the contracting authority before you use it.

Batch check on the server. For many invoices at once, without your program or browser staying connected the whole time: upload files, start, fetch the results later. From the Automate plan. The invoices stay encrypted on our server in Germany until checked and are deleted right after. The results stay for seven days, then we delete them. When everything is done, an email goes to the account address. In a company account the owner can switch this off for the other users (PATCH /v1/org/settings with { "stapel_ablage": false }).

Calls

Each file counts against the weekly quota. When it is used up, the batch stops (status: "angehalten", grund: "kontingent"); the remaining files stay unchecked and are deleted. The server checks such batches only on slots that are free at the moment; direct checks go first.

Returns the check result as a validation report in PDF/A-3b, ready to file and pass on. The report states the result, every message with rule id and field, the time of the check, the format and profile detected, the SHA-256 checksum of the file checked and the rule set, that is the versions of the tools used. Every call runs a fresh check and counts against the weekly quota like any validation. Available as the MCP tool validation_report and over REST as POST /v1/report.

Input

Output

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

Example

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