ZUGFeRD to XRechnung Converter

ZUGFeRD to XRechnung e-invoice converter: checks a ZUGFeRD or Factur-X invoice (PDF or CII XML), tells you which XRechnung fields are missing, and writes the XRechnung XML only after it passes the official XRechnung 3.0.2 validation.

Who it is for

• Suppliers of German public bodies that produce ZUGFeRD or Factur-X invoices and must deliver XRechnung.
• ERP and accounts receivable teams that want to know, per invoice, exactly which mandatory XRechnung terms (Leitweg-ID, seller contact, electronic addresses, payment data) are still missing.
• Developers of e-invoicing integrations who need a converter that fails closed instead of producing an XRechnung that the recipient portal rejects.

What it does

• Accepts hybrid ZUGFeRD or Factur-X PDFs and direct CII XML: file upload, HTTPS URL, inline XML, Base64 or a key-value store record. Up to 100 documents per run.
• Validates the source first (PDF/A-3 container, embedded XML, ZUGFeRD 2.5 / Factur-X 1.09 rules).
• Supports the D16B profiles BASIC, EN16931 and EXTENDED. MINIMUM and BASIC WL do not carry enough invoice data and are rejected.
• ZUGFeRD 1.0 (BASIC, COMFORT, EXTENDED) gets an automatic upgrade attempt to CII D16B with the pinned Mustangproject 2.24.0 engine. If the legacy document cannot be upgraded safely, the result says so.
• Converts to XRechnung UBL 2.1 or CII D16B and validates the target with the pinned KoSIT validator against XRechnung 3.0.2 (configuration release 2026-01-31).
• Turns the validator findings into a typed list of missing inputs (conversion.missingInputs), so you see which business terms to supply.
• Lets you add missing terms through overrides. An override can only add a term that is absent; it never replaces a value from the invoice.
• Compares the converted invoice with the source on the EN 16931 business-term level. The target XML is stored only when validation passes and nothing from the source was lost.

It never invents business data and never emits a target file that did not pass validation.

How to use it

1. Open the Input tab and upload your ZUGFeRD or Factur-X files, or add documents under API documents (each item has exactly one of url, xml, base64 or keyValueStoreKey).
2. Choose the Target XRechnung syntax: UBL (default) or CII.
3. Click Start. Each document becomes one row in the dataset with a conversion.status.
4. If the status is NEEDS_INPUT, read conversion.missingInputs, add the values as overrides and run it again.
5. When the status is CONVERTED, download the XRechnung XML from the run's key-value store (records starting with ARTIFACT-).

Input settings

Setting	Meaning
invoiceFiles	Uploaded ZUGFeRD or Factur-X PDFs or CII XML files
documents	Documents for API use: url, xml, base64 or keyValueStoreKey, with optional documentId and fileName
targetSyntax	UBL (default) or CII
targetRuleset	LATEST_SUPPORTED (default) resolves to XRechnung 3.0.2, release 2026-01-31
overrides	Missing business terms to add: businessTermId, value, reason, and schemeId for electronic addresses
storeConvertedXml	Store the validated XRechnung XML in the key-value store (default on)
storeExtractedXml, storeTechnicalReports	Also store the extracted source XML and the validation reports (default off)
maxFindingsPerDocument	Validation findings returned per document, 1 to 500 (default 100)

Example input:

{
  "documents": [
    {
      "documentId": "official-zugferd-sample",
      "fileName": "zugferd_2p0_EN16931_Einfach.pdf",
      "url": "https://raw.githubusercontent.com/ZUGFeRD/corpus/master/ZUGFeRDv2/correct/intarsys/EN16931/zugferd_2p0_EN16931_Einfach.pdf"
    }
  ],
  "targetSyntax": "UBL",
  "maxFindingsPerDocument": 20
}

Example overrides (the terms that can be added: BT-10, BT-31, BT-34, BT-37, BT-38, BT-41, BT-42, BT-43, BT-49, BT-52, BT-53, BT-81, BT-83, BT-84):

{
  "overrides": [
    { "businessTermId": "BT-10", "value": "04011000-12345-06", "reason": "Leitweg-ID supplied by the buyer" },
    { "businessTermId": "BT-34", "value": "billing@seller.example", "schemeId": "EM", "reason": "Seller e-invoice address from master data" },
    { "businessTermId": "BT-41", "value": "Max Mustermann", "reason": "Seller contact from master data" }
  ]
}

Every override needs a reason; electronic addresses (BT-34, BT-49) also need a schemeId. The row records each applied override with a SHA-256 of the value, not the value itself.

Output

One row per document. Shortened example from a real run of the example input above: the official ZUGFeRD sample is a valid ZUGFeRD invoice, but it lacks five terms that XRechnung requires, so the result is NEEDS_INPUT.

{
  "itemId": "official-zugferd-sample",
  "fileName": "zugferd_2p0_EN16931_Einfach.pdf",
  "processingStatus": "SUCCEEDED",
  "conformanceStatus": "REJECTED",
  "billable": true,
  "source": {
    "container": "PDF_A_3",
    "syntax": "CII_INVOICE",
    "sha256": "29842457f57143aba5da78fdf390aba773c965e60b1caab93dfff3e9d4c802f4",
    "standard": { "family": "ZUGFERD_FACTUR_X", "profile": "ZUGFERD_EN16931", "scenario": "ZUGFeRD 2.5 / Factur-X 1.09 EN16931" }
  },
  "conversion": {
    "status": "NEEDS_INPUT",
    "sourceSyntax": "CII",
    "targetSyntax": "UBL",
    "targetRuleset": "XRECHNUNG_3_0_2_2026_01_31",
    "missingInputs": [
      { "businessTermId": "BT-10", "normalizedPath": "/references/buyerReference", "targetRuleIds": ["BR-DE-15"], "allowedOverride": true, "valueType": "STRING" },
      { "businessTermId": "BT-34", "normalizedPath": "/parties/seller/electronicAddress", "targetRuleIds": ["PEPPOL-EN16931-R020"], "allowedOverride": true, "valueType": "ELECTRONIC_ADDRESS", "schemeIdRequired": true },
      { "businessTermId": "BT-41", "normalizedPath": "/parties/seller/contact/name", "targetRuleIds": ["BR-DE-2"], "allowedOverride": true, "valueType": "STRING" }
    ],
    "appliedOverrides": [],
    "upgrade": { "status": "NOT_REQUIRED" },
    "targetArtifact": {}
  },
  "sourceValidation": {
    "conformanceStatus": "ACCEPTED",
    "container": { "type": "PDF_A_3", "pdfaStatus": "COMPLIANT", "embeddedFileName": "zugferd-invoice.xml" }
  },
  "report": {
    "overall": "NON_CONFORMANT",
    "engine": {
      "counts": { "fatal": 0, "error": 5, "warning": 0, "information": 0 },
      "findings": [
        { "severity": "ERROR", "ruleId": "BR-DE-15", "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden." }
      ]
    }
  }
}

Main fields:

Field	Meaning
conversion.status	CONVERTED, NEEDS_INPUT, UNSUPPORTED or NOT_EVALUATED (see below)
conversion.missingInputs	Missing XRechnung terms: business term, the rule that requires it, and whether an override may add it
conversion.appliedOverrides	The overrides that were used, with reason and value hash
conversion.upgrade	Result of the ZUGFeRD 1.0 upgrade step, when one was needed
sourceValidation	Validation of the ZUGFeRD or Factur-X source, including the PDF/A-3 container
report	XRechnung validation of the target: findings with rule IDs, validator steps, and rulesetSnapshot with the exact versions and digests
migrationDiff	Comparison of source and converted invoice on the EN 16931 business-term level
billable	Whether this row was charged

Conversion states:

• CONVERTED: the target XML was generated, passed XRechnung validation and carries the same business content as the source. The file is in the key-value store.
• NEEDS_INPUT: the source is usable, but mandatory XRechnung terms are missing. Supply them as overrides.
• UNSUPPORTED: the profile or version is outside the supported list, or the converted invoice would not carry everything the source contains (error.code SEMANTIC_MIGRATION_LOSS_DETECTED). No target file is written.
• NOT_EVALUATED: an engine could not finish its check. Not charged.

Pricing

Pay per event:

Event	Price
Document processed (one document that was evaluated, whatever the conversion state)	$0.01
Actor start (per GB of memory, once per run)	$0.00005

Example: 1,000 invoices in one run cost 1,000 x $0.01 = $10.00, plus a few hundredths of a cent for the start. Documents that could not be processed (billable: false) are free. A second run with overrides for the same invoice is a new evaluation and is charged again.

Use it through the API

Run it from your own code with the Apify API or client libraries (Python, JavaScript), or connect it to Make, Zapier or n8n. Send documents as url, xml or base64 items in documents, read the dataset items of the run, and fetch the converted XML from the run's key-value store. The API tab of this page shows ready-made code.

What it does not do

This is an assisted conversion with evidence, not a guarantee that every ZUGFeRD document can become an XRechnung. It does not make legal, tax, authenticity, signature or recipient acceptance decisions, and it does not send the invoice to a portal or to Peppol.

FAQ

Why is my valid ZUGFeRD invoice NEEDS_INPUT? XRechnung requires terms that ZUGFeRD does not, most often the buyer reference (Leitweg-ID, BT-10), the seller contact (BT-41 to BT-43), the electronic addresses of seller and buyer (BT-34, BT-49) and payment instructions. conversion.missingInputs lists them for your document.

Can an override change a value in the invoice? No. Overrides only add allowlisted terms that are absent. Existing values are never replaced.

Why did I get UNSUPPORTED although the target validated? The converter also checks that nothing from the source was lost. If the source contains content that it cannot prove was carried over to the XRechnung, it stops instead of delivering a file that differs from your invoice.

Which XRechnung version is used? XRechnung 3.0.2 with the KoSIT validator configuration of 2026-01-31. Every row lists the exact versions and digests in report.rulesetSnapshot.

Does it read old ZUGFeRD 1.0 invoices? It tries: the legacy XML is validated and upgraded to CII D16B first. The row marks this path with legacySourceToUpgradeIntegrity: NOT_PROVEN, and unsupported legacy documents end as UNSUPPORTED.

Is my invoice data stored? Only in your own run storage. The converted XML is stored by default (storeConvertedXml); the extracted source XML and the technical reports only when you turn them on.

Support and feedback

• Found a bug or missing a field? Open an issue on the Issues tab of this Actor. We reply within 48 hours and ship most fixes within a few days.
• Have an idea for a feature? Issues are the fastest way to get it built.
• If the Actor saves you time, a short review on this page helps other users find it.