XRechnung REST API: The Complete Toolkit for German Public Sector E-Invoicing

XRechnung is not optional for German public sector suppliers. Since November 2020, every invoice submitted to a German federal authority must be in XRechnung format. Since April 2020, state governments began rolling out the same requirement. By 2025, the mandate covers virtually every level of German public administration — federal, state, and municipal. If your product serves businesses that invoice the German public sector, XRechnung support is a hard legal requirement, not a feature request.

XRechnung is also the most technically demanding format in the German e-invoicing landscape. Unlike ZUGFeRD or Factur-X — which wrap CII XML inside a familiar PDF/A-3 container that any accountant can open and read — XRechnung is pure XML. No PDF. No visual layer. 100% machine-readable. This makes it faster and more interoperable for automated B2G workflows, but it creates specific challenges: you cannot visually verify an XRechnung invoice without a dedicated viewer, the Leitweg-ID routing identifier is mandatory and cannot be extracted from a source PDF, and the format is governed by KoSIT (Koordinierungsstelle für IT-Standards) which publishes a new CIUS version roughly every twelve months.

InvoiceXML provides a complete XRechnung API toolkit covering every operation: convert any PDF to XRechnung, create XRechnung from structured data, validate against the official CIUS-REC-DE Schematron, render XRechnung as a human-readable PDF preview, and extract structured data from XRechnung files. This post covers every tool, explains the B2G submission infrastructure unique to XRechnung, and addresses the Leitweg-ID and syntax-choice questions that trip up most teams building XRechnung support for the first time.

What is XRechnung? The B2G standard explained

XRechnung is Germany's national CIUS (Core Invoice Usage Specification) of EN 16931, maintained by KoSIT. A CIUS is a constrained and extended version of the European core invoice standard — it takes EN 16931's 200+ business rules, adds approximately 20 additional German-specific rules (BR-DEX-xx codes), makes some optional EN 16931 fields mandatory, and prohibits some fields that EN 16931 permits.

The critical difference from every other format in this series: XRechnung produces pure XML with no PDF wrapper. The output of a /v1/transform/to/xrechnung call is an .xml file, not a .pdf. There is no visual layer. The invoice data exists only in structured form.

XRechnung supports two XML syntaxes — a deliberate choice from EN 16931 which mandates support for both:

XRechnung
├── CII syntax (UN/CEFACT Cross-Industry Invoice)
│   └── Root: <rsm:CrossIndustryInvoice>
│       └── SpecificationIdentifier: urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0
└── UBL syntax (OASIS Universal Business Language)
    └── Root: <Invoice>
        └── CustomizationID: urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0

Both syntaxes are legally equivalent. The government portals accept both. The choice is yours — but it has practical implications covered below.

The Leitweg-ID: what it is and why it matters

The Leitweg-ID is the single most important XRechnung-specific concept for developers to understand, and the one most likely to cause a rejected invoice at a government portal.

It is a hierarchical routing identifier assigned by the German public sector buyer. It appears in the BuyerReference field (BT-10) of the XRechnung and tells the receiving portal exactly which department, cost centre, or organisational unit within a government agency should receive the invoice. Its format is:

{TopLevelIdentifier}-{SubLevelIdentifier}-{CheckDigit}
Examples:
04011000-1234567890-06
991-00001-08
04011000-0001-03

The Leitweg-ID is never on the source PDF. It is not invoice data — it is routing infrastructure, similar to a sort code in banking. It is assigned by the public sector buyer and communicated to the supplier through a contract, procurement portal, or buyer onboarding document. It must be obtained from the buyer before the first invoice is submitted.

This has a direct API implication: unlike all other InvoiceXML conversion endpoints where every required field can potentially be extracted from the source document, the XRechnung transform endpoint requires BuyerReference to be supplied explicitly when the source is a PDF. The API cannot extract a Leitweg-ID from a PDF because it was never there to begin with.

# BuyerReference is REQUIRED for XRechnung — it cannot be extracted from the PDF
curl -X POST https://api.invoicexml.com/v1/transform/to/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "BuyerReference=04011000-1234567890-06" \
  -F "syntax=cii"

If BuyerReference is missing, the API returns a 4002 model validation error immediately — before running OCR or extraction — with a clear message explaining that the Leitweg-ID must be supplied by the user, not extracted from the document:

{
  "type": "...",
  "title": "Validation Failed",
  "status": 400,
  "errorCode": 4002,
  "detail": "BuyerReference is required for XRechnung conversion.",
  "errors": {
    "BuyerReference": [
      "XRechnung invoices submitted to German public sector buyers require a valid Leitweg-ID in BuyerReference (e.g. 04011000-1234567890-06). This identifier is provided by your buyer — it cannot be extracted from the source document."
    ]
  }
}

CII or UBL syntax? How to choose

Both syntaxes produce legally valid XRechnung. The portals accept both. Your choice should be driven by what the rest of your stack uses:

Choose CII (syntax=cii) if:

• Your system already generates ZUGFeRD or Factur-X (both use CII — you share the same data model and validation layer)
• You want to maintain a single XML syntax across all your European e-invoice formats
• Your downstream systems consume ZUGFeRD and you want format parity

Choose UBL (syntax=ubl) if:

• Your system already generates UBL for Peppol (XRechnung UBL shares the same namespace as Peppol BIS UBL)
• You operate in markets beyond Germany and want a single syntax for Peppol-compatible invoices across Belgium, Netherlands, Nordics, and Germany
• Your team has more UBL experience than CII experience

The InvoiceXML API defaults to CII (syntax=cii) which is the more common choice for teams operating primarily in the German market. Switch to syntax=ubl with a single parameter change — no other integration changes required.

Here is the specification identifier difference between the two:

<!-- XRechnung 3.0.2 — CII syntax -->
<rsm:ExchangedDocumentContext>
  <ram:GuidelineSpecifiedDocumentContextParameter>
    <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0</ram:ID>
  </ram:GuidelineSpecifiedDocumentContextParameter>
</rsm:ExchangedDocumentContext>

<!-- XRechnung 3.0.2 — UBL syntax -->
<cbc:CustomizationID>
  urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0
</cbc:CustomizationID>

Both use the same specification identifier string — only the XML element that carries it differs between syntaxes.

Where XRechnung invoices are submitted: the German B2G portal landscape

XRechnung is not sent by email. It is submitted to government portals or transmitted via the Peppol network. Understanding the submission infrastructure is essential for any team building end-to-end B2G invoicing:

ZRE (Zentrale Rechnungseingangsplattform des Bundes) — the federal government's central invoice receiving platform. Operated by the German federal government for invoices addressed to federal authorities. Accepts XRechnung in both CII and UBL syntax via web upload, PEPPOL, email (for accredited senders), and SFTP. URL: xrechnung.bund.de.

OZG-RE (Online-Zugangsgesetz Rechnungseingang) — the primary portal for invoices to state (Länder) and municipal authorities. Most German states have connected to OZG-RE for their e-invoice receiving infrastructure. Some states operate their own portals (Bavaria uses BayRE, for example) but all accept standard XRechnung.

Peppol — the recommended transmission channel for automated workflows. A German supplier registered on the Peppol network can submit XRechnung to any government entity with a Peppol participant identifier, without interacting with web portals. The InvoiceXML API generates the XRechnung document — transmission via Peppol is handled by your Peppol access point provider.

For developers: the InvoiceXML API covers document generation and validation. Portal submission and Peppol transmission are separate infrastructure layers outside the API's scope. What the API guarantees is that the XRechnung document it produces will be accepted by any of these portals — because it is validated against the official KoSIT Schematron before delivery.

The InvoiceXML XRechnung API toolkit

Base URL: https://api.invoicexml.com
Authentication: Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Tool 1: Convert any PDF to XRechnung

What it does: Accepts any invoice document and returns a validated XRechnung XML file in your chosen syntax (CII or UBL). The AI pipeline handles OCR for scanned documents, extracts every extractable EN 16931 field from the source, maps the data to the XRechnung schema, and validates against both the EN 16931 Schematron and the CIUS-REC-DE national extension rules before returning the output.

The key distinction from all other transform endpoints: BuyerReference (Leitweg-ID) is a required parameter that cannot be extracted from the source document. You must supply it explicitly.

When to use it: A supplier has been invoicing a government agency by PDF email for years and now needs to submit via XRechnung. You are building a portal or integration that helps public sector suppliers comply with the mandate. Your ERP generates PDF invoices and you want to add an automated XRechnung conversion step before portal submission.

# CII syntax (default)
curl -X POST https://api.invoicexml.com/v1/transform/to/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "BuyerReference=04011000-1234567890-06" \
  -F "syntax=cii" \
  -F "version=3.0.2"

# UBL syntax
curl -X POST https://api.invoicexml.com/v1/transform/to/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "BuyerReference=04011000-1234567890-06" \
  -F "syntax=ubl" \
  -F "version=3.0.2"

The response is a binary XML file (application/xml). There is no PDF wrapper — XRechnung is pure XML by design. If you need a human-readable version of the output for review before submission, use the render endpoint (Tool 4 below).

Accepted input formats: PDF (native and scanned), JPEG, PNG, TIFF, WEBP, HEIC, DOCX, XLSX.

Tool 2: Create XRechnung from JSON data

What it does: Accepts structured invoice data as form fields and returns a validated XRechnung XML file. No source document required. You supply the data — including the mandatory BuyerReference — and the API generates compliant XRechnung output in your chosen syntax.

When to use it: Your ERP or billing system already has invoice data in structured form and you want to generate XRechnung directly without going through a PDF intermediary. You are building an invoicing module for public sector suppliers and want to output XRechnung natively. You process high volumes of B2G invoices and cannot afford the latency of AI extraction — structured input with direct XML generation is faster and more predictable.

curl -X POST https://api.invoicexml.com/v1/create/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "InvoiceNumber=LR-2025-04712" \
  -F "IssueDate=2025-05-15" \
  -F "PaymentDueDate=2025-06-15" \
  -F "SellerName=Weber Consulting GmbH" \
  -F "SellerTaxId=DE334512678" \
  -F "SellerStreet=Kaiserstraße 5" \
  -F "SellerPostcode=60311" \
  -F "SellerCity=Frankfurt am Main" \
  -F "SellerCountry=DE" \
  -F "SellerContactName=Max Weber" \
  -F "SellerPhone=+49 69 12345678" \
  -F "[email protected]" \
  -F "SellerElectronicAddress=DE334512678" \
  -F "SellerElectronicAddressScheme=0204" \
  -F "BuyerName=Bundesministerium für Digitales" \
  -F "BuyerStreet=Wegbereiterstraße 8" \
  -F "BuyerPostcode=53113" \
  -F "BuyerCity=Bonn" \
  -F "BuyerCountry=DE" \
  -F "BuyerReference=04011000-1234567890-06" \
  -F "BuyerElectronicAddress=991-00001-08" \
  -F "BuyerElectronicAddressScheme=0204" \
  -F "purchase_order_reference=BM-2025-PO-00142" \
  -F "Currency=EUR" \
  -F "TaxBasisTotal=8500.00" \
  -F "TaxTotalAmount=1615.00" \
  -F "GrandTotalAmount=10115.00" \
  -F "PaymentMeansCode=58" \
  -F "IBAN=DE12500105170648489890" \
  -F "BIC=BELADEBEXXX" \
  -F "syntax=cii" \
  -F "Lines[0][description]=IT-Beratung Digitalisierungsstrategie" \
  -F "Lines[0][quantity]=85" \
  -F "Lines[0][unitPrice]=100.00" \
  -F "Lines[0][lineTotal]=8500.00" \
  -F "Lines[0][unitCode]=HUR" \
  -F "Lines[0][taxPercentage]=19" \
  -F "Lines[0][taxCategoryCode]=S"

Note purchase_order_reference in the example — this is BT-13, the buyer's purchase order number. For public sector invoices this field is frequently required by the contracting authority. Many government contracts specify that invoices must reference the purchase order number; ZRE and OZG-RE portals often use it for routing and matching. It is optional at the EN 16931 level but worth including whenever you have it.

XRechnung-specific mandatory fields: XRechnung requires several fields that are optional under base EN 16931. Beyond the Leitweg-ID (BuyerReference), the CIUS mandates seller contact information — SellerContactName (BT-41), SellerPhone (BT-42), and SellerEmail (BT-43) — as well as electronic addresses for both parties: SellerElectronicAddress (BT-34) and BuyerElectronicAddress (BT-49). These fields enable automated routing and communication through government portals. Omitting any of them results in a 4002 validation error before XML generation begins.

The Skonto (cash discount) field: XRechnung has a specific proprietary format for Skonto terms that is unique in the European e-invoicing ecosystem. EN 16931 does not support structured cash discount terms in the XML — it only allows them as free text in the payment notes field. XRechnung's CIUS specifies a machine-readable Skonto format using a structured string in the PaymentTerms field:

#SKONTO#TAGE=14#PROZENT=2.00#BASISBETRAG=10115.00#

This format is understood by German accounting systems and portals but is not a standard EN 16931 construct. If your customers use Skonto and need it machine-readable in their XRechnung output, supply it via the payment_terms parameter and the API will format it correctly according to the CIUS specification.

Tool 3: Validate XRechnung

What it does: Accepts an XRechnung XML file in either CII or UBL syntax and runs a two-layer validation pipeline: EN 16931 Schematron (the European core rules) plus CIUS-REC-DE (the German national extension rules published by KoSIT). The syntax is detected automatically from the root element.

Why two-layer validation is non-negotiable for XRechnung:

A document can pass all 200+ EN 16931 business rules and still be rejected by the ZRE portal because it fails one of the 20+ CIUS-REC-DE rules. These German-specific rules include:

• BR-DEX-01: The specification identifier must be one of the valid XRechnung CIUS identifiers. A ZUGFeRD EN 16931 spec ID will not be accepted.
• BR-DEX-04: Seller's VAT identification number or seller's tax registration number must be present.
• BR-DEX-05: BuyerReference (the Leitweg-ID) must be present and non-empty.
• BR-DEX-09: If payment means code is 58 (SEPA credit transfer), the IBAN must be present.
• BR-DEX-14 through BR-DEX-18: Various additional constraints on party identifiers and references.

Running EN 16931 validation alone is not enough. You need the CIUS-REC-DE Schematron as a second pass. InvoiceXML runs both automatically and reports violations from each layer separately, so you know whether a problem is a fundamental EN 16931 violation or a German-specific requirement.

When to use it: Before submitting to ZRE, OZG-RE, or any state portal. During development when testing your XRechnung generation pipeline. When processing incoming XRechnung files from subcontractors or partners before forwarding to your ERP. When running a compliance audit on a batch of archived XRechnung files.

curl -X POST https://api.invoicexml.com/v1/validate/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

Successful validation:

{
  "valid": true,
  "detectedSyntax": "cii",
  "detectedVersion": "3.0.2",
  "specificationIdentifier": "urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0",
  "errorCount": 0,
  "warnings": []
}

Validation failure with CIUS-specific rule:

{
  "valid": false,
  "detectedSyntax": "cii",
  "detectedVersion": "3.0.2",
  "errorCount": 1,
  "errors": [
    {
      "rule": "BR-DEX-05",
      "message": "XRechnung invoices must contain a BuyerReference (Leitweg-ID). This field is mandatory for submission to German public sector portals.",
      "source": "schematron",
      "severity": "error",
      "layer": "cius-rec-de"
    }
  ]
}

The layer field distinguishes EN 16931 violations from CIUS-REC-DE violations — useful for communicating the nature of the error to users. A layer: en16931 error means the invoice fails the European standard and would be rejected everywhere. A layer: cius-rec-de error means it passes EN 16931 but fails the German national requirements specifically.

Add ?errors=friendly for plain-language error descriptions suitable for surfacing in user interfaces.

Tool 4: Preview XRechnung as a human-readable PDF

What it does: Accepts an XRechnung XML file and renders it as a clean, professionally formatted PDF invoice. Every EN 16931 Business Term is mapped to a legible invoice layout — seller and buyer details, line items, tax breakdown, payment instructions, all reference fields, and the Leitweg-ID clearly labelled.

Why this tool matters more for XRechnung than for any other format:

ZUGFeRD and Factur-X already have a human-readable PDF layer — every file in those formats is simultaneously a readable invoice. XRechnung has no PDF layer at all. Finance teams, project managers, and AP staff who receive or generate XRechnung files have no way to read them without specialist software.

This creates two real problems:

Before submission: A supplier generating XRechnung needs to verify the invoice is correct before sending it to a government portal. With a PDF invoice they can just open it. With XRechnung they are staring at several hundred lines of XML. The preview endpoint gives them a readable version for pre-submission review — catching errors in line item descriptions, amounts, or tax rates before they result in a rejected or disputed invoice.

After receipt: A procurement officer at a government agency receives XRechnung files from contractors. They need to approve payments but cannot read raw XML. Their ERP may display the data, but when investigating a discrepancy or responding to a supplier query, having a printable PDF of the invoice is essential.

curl -X POST https://api.invoicexml.com/v1/render/xrechnung/to/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  --output preview.pdf

The rendered PDF shows the Leitweg-ID in the buyer reference section, the XRechnung version and specification identifier in the document header, and the Skonto terms in human-readable format if present. Both CII and UBL syntax input are supported — the syntax is detected automatically.

Important: The rendered PDF is for visual review only. It has no legal standing and should not be submitted as an invoice to any portal. The XRechnung XML file remains the authoritative legal document.

Tool 5: Extract structured data from XRechnung

What it does: Accepts an XRechnung XML file in either syntax and extracts all invoice fields as structured JSON. The JSON follows the normalised EN 16931 data model regardless of whether the input was CII or UBL syntax — your downstream processing code does not need syntax-specific handling.

When to use it: You receive XRechnung files from subcontractors and need to import the data into your ERP or project management system. You are building an AP automation workflow that processes incoming public sector invoices. You need to reconcile incoming XRechnung invoices against purchase orders in your system. You want to extract the Leitweg-ID and purchase order reference from received invoices for routing to the correct internal cost centre.

curl -X POST https://api.invoicexml.com/v1/extract/json \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

The JSON response includes all standard invoice fields plus XRechnung-specific fields:

{
  "invoiceNumber": "LR-2025-04712",
  "issueDate": "2025-05-15",
  "dueDate": "2025-06-15",
  "buyerReference": "04011000-1234567890-06",
  "purchaseOrderReference": "BM-2025-PO-00142",
  "specificationIdentifier": "urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_3.0",
  "detectedSyntax": "cii",
  "seller": {
    "name": "Weber Consulting GmbH",
    "taxId": "DE334512678",
    "address": { ... }
  },
  "buyer": {
    "name": "Bundesministerium für Digitales",
    "address": { ... }
  },
  "totals": {
    "netAmount": 8500.00,
    "taxAmount": 1615.00,
    "grossAmount": 10115.00,
    "currency": "EUR"
  },
  "lines": [ ... ],
  "taxBreakdown": [ ... ],
  "paymentMeans": {
    "code": "58",
    "iban": "DE12500105170648489890",
    "bic": "BELADEBEXXX"
  }
}

The buyerReference field contains the Leitweg-ID, making it straightforward to route incoming invoices to the correct internal department or cost centre automatically.

The KoSIT release cycle: why XRechnung validation breaks every year

KoSIT publishes a new XRechnung CIUS version approximately once per year, typically in Q4. Each release introduces updated Schematron validation artefacts, sometimes changes business rule semantics, and sets a deprecation deadline for the previous version — typically six months after release. After the deprecation deadline, portals like ZRE will reject invoices declaring the old CIUS version.

The XRechnung version history:

This annual release cycle creates a specific maintenance commitment for self-managed implementations. When a new version ships you must: download the new KoSIT Schematron artefacts from github.com/itplr-kosit/xrechnung-schematron, test them against your invoice test suite to catch any breaking semantic changes, deploy before the old version's deprecation deadline, and update any hardcoded version strings in your generation layer.

Miss the deadline and your customers start receiving rejection messages from government portals. They will contact your support team, not KoSIT.

InvoiceXML deploys each new XRechnung version ahead of its effective date. The API always generates the current recommended version by default. You can pin to an older version with the version parameter during a transition period, but the default always tracks the current production-recommended release. No Schematron downloads, no deployment windows, no deprecation anxiety.

Security and compliance for B2G invoice processing

XRechnung invoices submitted to government portals contain particularly sensitive data: supplier tax identification numbers, bank account details, contract references, the Leitweg-ID which identifies the government department, and the full financial terms of public procurement contracts. In Germany this data is subject to DSGVO (German GDPR implementation) and, in many cases, additional confidentiality obligations under public procurement law.

InvoiceXML processes all documents in memory only. Nothing is written to disk. Nothing is retained after the API response is delivered. No invoice data is transmitted to third parties or used for model training. This is not a configurable option — it is the default and only architecture, enforced at the infrastructure level. GDPR and HIPAA certifications are independently audited.

Our security team monitors the API infrastructure 24/7. The status page shows live uptime history since launch — 99.95% uptime is a contractual SLA, not a marketing figure. For B2G workflows where invoice submission deadlines are legally significant, infrastructure reliability is not a nice-to-have.

Complete XRechnung API endpoint reference

All endpoints auto-detect CII vs UBL syntax from the root element — no syntax parameter required for validation, preview, and extract. The syntax parameter is only needed on generate/transform endpoints where you specify the desired output syntax.

Full OpenAPI 3.1 schema available at api.invoicexml.com/openapi.

Supported XRechnung versions

Note: XRechnung 3.0, 3.0.1, and 3.0.2 share the same specification identifier string in the XML — the minor version is tracked internally by KoSIT but the declared identifier is xrechnung_3.0 for all three. Version detection in the InvoiceXML validator uses the Schematron artefact version, not the identifier string alone.

Get started

Upload any PDF invoice at invoicexml.com/pdf-to-xrechnung to try the conversion online — note that you will need a Leitweg-ID to test the full conversion. If you do not have one, you can use the sample ID 04011000-1234567890-06 to see the tool in action.

To integrate via API, start your free 30-day trial. The permanent free tier of 100 credits per month supports ongoing development without a paid plan.

Related resources:

• How the AI document pipeline works
• Full API documentation
• ZUGFeRD API: the complete B2B toolkit
• CII API: the complete toolkit
• UBL API: the complete toolkit
• Factur-X API: the complete toolkit
• Preview XRechnung as PDF
• Automation and no-code integrations
• Pricing

InvoiceXML is the compliance layer for modern European e-invoicing. It covers XRechnung (all versions, CII and UBL syntax), ZUGFeRD, Factur-X, CII, UBL, and EN 16931 via a single REST API — with stateless processing, CIUS-REC-DE validation, and automatic KoSIT version tracking on your side.