Guide for developers

Validate XRechnung: common errors and the API fix

A syntactically correct XRechnung is not automatically a valid XRechnung. This guide shows the most common real-world validation failures and how to catch them automatically inside your pipeline.

Need to check a single invoice?

Use the web validator for quick browser-based checks with XML or ZUGFeRD PDF files.

Open validator

Need to automate e-invoicing?

Use the API for recurring validation, generation, and retrieval inside your software.

Open developer page

Why validation matters

Since January 1, 2025, companies in Germany must be able to receive structured e-invoices in B2B scenarios. Public-sector channels such as ZRE or OZG-RE have enforced structured invoice validation for much longer. If an invoice does not meet the XRechnung schemas, it is simply rejected.

Validation failures are expensive: with manual workflows they create rework, delayed payment, and support effort. If you generate invoices programmatically, automated validation must be a fixed step in the generation pipeline.

The 5 most common XRechnung mistakes

Across many validated documents, five categories show up again and again:

→ Wrong or missing CustomizationID - XRechnung UBL expects exactly `urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0` for current 3.x documents. Deviations are rejected immediately.
→ Missing mandatory EN 16931 fields - especially due date, tax identifiers, or other conditionally required business terms.
→ Invalid tax treatment - missing or contradictory tax category codes. Exempt services need the correct tax category plus a reason code.
→ Date format problems - XRechnung expects ISO 8601 (`YYYY-MM-DD`). Timestamps or localized dates such as `01.04.2025` are rejected.
→ Broken totals - `TaxExclusiveAmount + TaxAmount` must match `TaxInclusiveAmount`. Float rounding is a classic source of mismatch.

Validate XRechnung in the browser

For manual checks, the web validator on this site is the fastest option. Upload the XML file and, after free registration, you get structured validation details including business-rule references, XML path, and a readable explanation.

The browser tool is great for spot checks, but it is not the right interface for recurring production validation. That is where the API becomes the real fit.

Validation via API - curl example

With the XInvoice API you can validate an XRechnung document in a single HTTP request and get structured EN 16931 findings back:

curl -X POST https://api.xinvoice.net/v1/invoices/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

Validate an XRechnung invoice via REST API

The response contains `valid` with `true` or `false`, a structured `errors` array, and optional warnings that do not necessarily block delivery.

How to wire validation into your pipeline

A common setup looks like this: your ERP or billing app generates the XML, the API validates it before delivery, and only documents with `valid: true` continue to the recipient or public platform.

That removes authority-side rejections before the invoice ever leaves your system. XInvoice gives you 100 free API calls in the first 30 days, which is enough for initial integration and realistic testing.

If you use asynchronous generation, your software can poll the status endpoint until the invoice is available. For quick tests you can also request synchronous processing with the `Prefer: respond-sync` header.