ZUGFeRD to XRechnung — turn a hybrid PDF into pure XML

What it does

A ZUGFeRD invoice carries a CII XML embedded in a PDF/A-3. But some recipients — especially German authorities or Peppol gateways — only accept the pure XRechnung XML, sometimes exclusively in the UBL syntax. The API extracts the embedded XML and returns it in the requested target syntax, validated against the current XRechnung specification.

Why you need this

• Government portals (ZRE federal, OZG-RE state) partly accept only XRechnung XML, not hybrid PDFs
• Peppol transport requires UBL XML; incoming ZUGFeRD must be converted
• Machine-readable processing in the ERP is faster with pure XML than by extracting from PDF
• Archiving strategies often split them: PDF/A-3 for legibility, pure XML for analytics

Minimal request

curl -X POST https://api.dokmatiq.com/v1/convert/zugferd-to-xrechnung \
  -H "Authorization: Bearer $DOKMATIQ_KEY" \
  -F "document=@invoice-zugferd.pdf" \
  -F "targetSyntax=UBL" \
  -o invoice-xrechnung.xml

Response: Content-Type: application/xml, status 200, body = valid XRechnung XML.

Request options

{
  "targetSyntax": "UBL",
  "targetVersion": "3.0",
  "enforceLeitwegId": true,
  "validate": true,
  "includeValidationReport": false
}

• targetSyntax: UBL or CII. UBL is the Peppol default; CII keeps the ZUGFeRD origin
• targetVersion: 3.0 (current XRechnung) or 2.3 for backward compatibility
• enforceLeitwegId: fails if no valid Leitweg-ID (BT-10) is present — useful before B2G dispatch
• validate: full Schematron validation (EN 16931 + XRechnung CIUS)
• includeValidationReport: additionally returns a JSON listing every checked rule

What is verified

Conversion runs in three stages:

1. Extraction — pull the CII from the PDF/A-3 per RFC 7292/PDF/A-3 conventions (factur-x.xml or zugferd-invoice.xml)
2. Transformation — CII → UBL (or CII → CII 3.0) with lossless transfer of all BT fields
3. Validation — against XSD and Schematron of the target specification

A ZUGFeRD in profile MINIMUM or BASIC WL fails conversion because XRechnung mandates complete line items and tax details. The error comes with a clear reference to the missing BT field.

Edge case: ZUGFeRD without a Leitweg-ID

Many ZUGFeRD invoices in B2B carry no Leitweg-ID. For B2G dispatch it is mandatory. Three options:

{
  "targetSyntax": "UBL",
  "enforceLeitwegId": false,
  "leitwegId": "991-33333TEST-33",
  "leitwegIdMode": "append"
}

• append — Leitweg-ID is added to BT-10 if empty
• replace — overwrites an existing Leitweg-ID
• strict — errors if not already present (default with enforceLeitwegId: true)

What it’s used for

• B2G dispatch from B2B systems — the ERP produces ZUGFeRD, the workflow converts for authorities
• Peppol onboarding — reformat incoming ZUGFeRD invoices for Peppol gateways
• Accounting integration — the ERP wants pure XML while the supplier sends hybrid
• Archive separation — PDF/A-3 for legibility, XML for machine analysis

Comparison with manual implementations

	Dokmatiq ZUGFeRD-to-XRechnung	Roll your own (XSLT)	Mustang (Java lib)	Peppol AP provider
PDF extraction	included	extra library needed	included	usually included
CII→UBL mapping	lossless, tested	many edge cases	included	usually included
Schematron validation	up-to-date (3.0)	maintain yourself	included	usually included
Leitweg-ID handling	configurable	build yourself	no	usually no
Pricing/scaling	API per call	operational effort	open source + ops	subscription

For one-off conversions, Mustang is fine. For production pipelines with variable source profiles and Schematron updates, operational effort quickly exceeds the API cost.

Common pitfalls

1. Missed ZUGFeRD 1.0 — the API explicitly rejects 1.0; upgrade to 2.x upstream or regenerate from raw data
2. Profile too small — MINIMUM lacks line items, conversion fails; configure the source system to emit at least EN16931
3. Embedded file name not factur-x.xml — older ZUGFeRD 2.0 documents still use zugferd-invoice.xml; auto-detected
4. Rounding errors on totals — XRechnung’s Schematron is stricter on total verification; some ZUGFeRD sources carry rounding errors surfaced by validation