XRechnung to JSON Parser

XRechnung parser: convert XRechnung to JSON. Parse XRechnung UBL 2.1 Invoice, UBL 2.1 CreditNote, or CII D16B XML into one stable EN 16931-oriented JSON contract, with the official KoSIT validation result next to the data.

Who it is for

• Accounts payable teams that receive XRechnung e-invoices (E-Rechnung) and need the invoice data as JSON for an ERP, a spreadsheet or a database.
• Developers who want one JSON model for both XRechnung syntaxes (UBL and CII) instead of writing two XML mappings.
• Integrators who need to know whether an invoice is technically conformant before it is posted.

Quick start

The following input uses an official XRechnung testsuite invoice pinned to an immutable source commit:

{
  "documents": [
    {
      "documentId": "official-ubl-smoke",
      "fileName": "01.01a-INVOICE_ubl.xml",
      "url": "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/b3791d47a2e1446b1751a27cb732aac294231293/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml"
    }
  ],
  "sourceSyntax": "UBL",
  "allowPartialNormalization": true,
  "storeTechnicalReports": false,
  "maxFindingsPerDocument": 100
}

Each submitted document produces one Dataset result with separate processing, technical conformance, normalization, billing, source-provenance, and invoice data fields.

What it does

• Accepts up to 100 XML documents by upload, inline XML, inline base64, HTTPS URL, or explicit key-value store record.
• Enforces a 5 MiB per-document and 100 MiB per-run limit.
• Detects UBL Invoice, UBL CreditNote, or CII and can enforce a caller-declared syntax.
• Runs KoSIT Validator 1.6.0 with the pinned XRechnung 3.0.2 configuration release 2026-01-31.
• Reports XML, XSD, Schematron, EN 16931, XRechnung, and mapping evidence separately.
• Maps the full declared EN 16931 syntax binding into the shared JSON model, with business-term trace entries and decimal strings.
• Can retain KoSIT XML and XHTML reports as opt-in KVS artifacts.

Invalid documents can still receive normalized data when XML parsing is safe. conformanceStatus and normalizationStatus are separate so a technically rejected document is never presented as conformant.

How to use it

1. Open the Actor and upload one or more XRechnung XML files under "Upload XRechnung XML", or add them as URLs in "API documents".
2. Leave "Source syntax" on AUTO, or set UBL or CII to reject other files.
3. Start the run. Each invoice becomes one row in the Dataset.
4. Read conformanceStatus first, then use the invoice object as your data.
5. Export the Dataset as JSON, CSV or Excel, or fetch it through the API.

Input settings

Field	What it does	Default
invoiceFiles	XML files uploaded in the Console (up to 100)	none
documents	API list; each item has exactly one of url, xml, base64, keyValueStoreKey, plus optional documentId and fileName	one KoSIT sample
sourceKeyValueStoreId	Key-value store that holds records named in keyValueStoreKey	none
sourceSyntax	AUTO, UBL or CII	AUTO
allowPartialNormalization	Return safely parsed fields even for non-conformant XML	true
storeTechnicalReports	Keep the KoSIT XML and HTML reports in the run key-value store	false
maxFindingsPerDocument	Maximum validation findings per invoice (1 to 500)	100

Output example

A shortened row from a real run on the official KoSIT sample invoice 01.01a-INVOICE_ubl.xml:

{
  "contractVersion": "einvoice-suite-result/1.0.0",
  "actorName": "xrechnung-to-json-parser",
  "itemId": "kosit-valid-sample",
  "fileName": "01.01a-INVOICE_ubl.xml",
  "processingStatus": "SUCCEEDED",
  "conformanceStatus": "ACCEPTED",
  "normalizationStatus": "COMPLETE",
  "billable": true,
  "source": {
    "sourceKind": "URL",
    "container": "XML",
    "syntax": "UBL_INVOICE",
    "standard": {
      "family": "XRECHNUNG",
      "profile": "XRECHNUNG_CIUS",
      "identifier": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
    }
  },
  "report": { "overall": "CONFORMANT" },
  "invoice": {
    "document": {
      "invoiceNumber": "123456XX",
      "issueDate": "2016-04-04",
      "invoiceTypeCode": "380",
      "invoiceCurrencyCode": "EUR"
    },
    "lines": [
      {
        "id": "Zeitschrift [...]",
        "item": { "name": "Zeitschrift [...]", "description": "Zeitschrift Inland" },
        "quantity": { "value": "1", "unitCode": "XPP" },
        "netAmount": { "amount": "288.79", "currency": "EUR" },
        "period": { "startDate": "2016-01-01", "endDate": "2016-12-31" },
        "vat": { "categoryCode": "S", "rate": "7" }
      }
    ]
  }
}

The invoice object also contains parties, references, process, totals, vatBreakdowns, paymentInstructions, paymentTerms, documentAllowancesCharges, supportingDocuments and a trace of EN 16931 business terms. Amounts are decimal strings, so no rounding happens in JSON.

Pricing

Pay per event:

Event	Price
document-processed (one evaluated invoice)	$0.005 ($5 per 1,000 invoices)
Actor start (per GB of memory)	$0.00005

Worked example: 200 XRechnung invoices in one run at the default 2 GB memory cost 200 x $0.005 = $1.00 plus 2 x $0.00005 for the start, so about $1.0001. Platform usage is included in the event price.

A document that cannot be read (for example a URL that does not answer) is returned with billable: false and is not charged. When your maximum charge per run is reached, the remaining documents get a free row with the error code BUDGET_LIMIT_REACHED instead of being processed.

Integrations and API

Run it from any language with the Apify API, for example with curl:

curl -X POST "https://api.apify.com/v2/acts/kamerozkan~xrechnung-to-json-parser/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents":[{"documentId":"inv-1","url":"https://example.com/invoice.xml"}]}'

The same call works from Make, Zapier, n8n and webhooks. For private files, put the XML into a key-value store and pass sourceKeyValueStoreId with keyValueStoreKey, or send it inline as xml or base64.

Product boundary

The result is integration-ready JSON, not a preconfigured connector for every ERP. Posting logic, chart-of-accounts rules, master-data resolution, duplicate handling, approval policy, and the final ERP field mapping remain system-specific.

The Actor does not make legal, tax, authenticity, signature, or recipient acceptance decisions.

FAQ

Does it read both XRechnung syntaxes? Yes. UBL 2.1 Invoice, UBL 2.1 CreditNote and UN/CEFACT CII D16B all map to the same JSON model.

What happens with an invalid XRechnung? You get conformanceStatus: REJECTED with the KoSIT findings. If the XML can be parsed safely and allowPartialNormalization is on, the invoice data is still returned and normalizationStatus tells you how complete it is.

Can I parse ZUGFeRD or Factur-X PDFs? Not with this Actor; it reads XML only. Use the ZUGFeRD / Factur-X PDF to JSON Actor from the same developer for hybrid PDF invoices.

Which XRechnung version is checked? XRechnung 3.0.2 with the KoSIT configuration release 2026-01-31 and KoSIT Validator 1.6.0. The versions are pinned, so the same file gives the same result on every run.

Are my invoices stored? Only in your own run storage. Technical reports are kept only when you turn on storeTechnicalReports.

Support

Found a file that is parsed wrongly or a field you need? Open an issue on the Actor's Issues tab with the file name and the run ID; replies usually come within one working day.

If the Actor saves you time, a short review on its Store page helps other users find it.