How to validate an XRechnung XML file (with code samples)

If you generate or receive XRechnung invoices, you need to check them against the official rules before delivery. A XRechnung document that fails validation will be rejected by the recipient's system. This guide shows you how to validate a XRechnung XML file with the InvoiceSpec API, read the structured validation report, and fix the most common rule violations.

What validation checks

A XRechnung invoice has to pass two layers of checks before it is considered valid:

• An XSD schema check confirms the XML is well-formed and the elements are in the right structure.
• A Schematron rule set encodes the EN 16931 business rules and the German-specific rules the CIUS adds on top.

Both layers are published by KoSIT, the German federal IT standards office. The current XRechnung version is 3.0.2. InvoiceSpec runs the same KoSIT XSD and Schematron checks the recipient's system will run, so a document that passes here passes on delivery.

Validate a XRechnung file with the API

The validate endpoint is POST /v1/invoice/xrechnung/validate. Send the raw XRechnung XML in the request body with the Content-Type set to application/xml, and pass your API key as a bearer token.

curl -X POST https://api.invoicespec.com/v1/invoice/xrechnung/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  -d @xrechnung.xml

The endpoint always returns 200 OK with a JSON body. Validation failures are reported as valid: false with a structured issue list, not as an HTTP error. Only infrastructure-level or request-level problems produce error responses.

Read the validation response

A valid document returns a short response:

{
  "valid": true,
  "version": "3.0.2",
  "syntax": "CII",
  "summary": { "errors": 0, "warnings": 0, "information": 0 },
  "issues": [],
  "requestId": "req_01HXYZ..."
}

An invalid document returns the same shape with valid: false and a populated issues array. Each issue carries a severity, the rule code, and a message that names the field or element at fault.

{
  "valid": false,
  "version": "3.0.2",
  "syntax": "CII",
  "summary": { "errors": 1, "warnings": 0, "information": 0 },
  "issues": [
    {
      "severity": "ERROR",
      "code": "BR-DE-15",
      "message": "An electronic address (BT-34) of the Seller is required."
    }
  ],
  "requestId": "req_01HXYZ..."
}

The summary object gives you the count of errors, warnings, and informational messages at a glance. The issues array gives you the detail you need to fix each one. The requestId is useful for support tickets when you need help tracing a specific validation run.

Handle the issue severities

Issues come in three severities:

• ERROR blocks delivery. The document fails validation and the recipient's system will reject it. Fix every error before sending.
• WARNING does not block delivery but flags something worth reviewing. Some recipients treat warnings as errors, so check with yours.
• INFORMATION is advisory. The document is valid, but the rule surfaces something you may want to know.

A document is only valid: true when the error count is zero. Warnings and informational messages do not affect the valid flag.

Fix the most common rule violations

Most XRechnung validation failures come from a small number of rules. Here are the ones that come up most often.

BR-DE-15: missing buyer reference

The BR-DE-15 rule requires a buyer reference (BT-10) to be present and non-blank. For public-sector invoices this is the Leitweg-ID, the German routing identifier that delivers the invoice to the right recipient system.

The rule checks presence only. It does not verify the format or a checksum of the buyer reference. That gap is a shared limitation in the standard KoSIT tooling, not an InvoiceSpec quirk.

Missing seller contact group

XRechnung rules BR-DE-5, BR-DE-6, and BR-DE-7 require a seller contact group with a contact point, a telephone, and an email. If you generate invoices with the API, include the seller.contact object in your request with all three fields.

Missing seller electronic address

The BR-DE-13 rule requires the seller to carry an electronic address (BT-34). Set seller.electronicAddress and seller.electronicAddressSchemeId in your request. The scheme identifier 9930 is the most common one for German VAT identifiers.

Validate without writing code

If you have a XRechnung file and want to check it without setting up an API call, use the free XRechnung Validator. Paste the XML or upload a file and get the same structured report in the browser, no signup required.

Next steps

• Read the full API reference for the XRechnung validate endpoint, including every response field and the error codes.
• Browse the invoice JSON schema explorer to see which request fields map to which EN 16931 business terms, so you can fix violations at the source.
• Learn how to generate a XRechnung invoice with a single API call, then validate the output before delivery.