# XRechnung & ZUGFeRD / Factur-X Parser – E-Invoice to JSON (`fast_data_asap/xrechnung-zugferd-einvoice-parser`) Actor

Convert German and EU e-invoices to clean JSON: XRechnung (UBL & CII), ZUGFeRD and Factur-X PDFs (embedded XML extracted automatically). Seller, buyer, Leitweg-ID, IBAN, totals, VAT breakdown, line items and plausibility checks. Pay only per parsed invoice.

- **URL**: https://apify.com/fast_data_asap/xrechnung-zugferd-einvoice-parser.md
- **Developed by:** [Fast Data](https://apify.com/fast_data_asap) (community)
- **Categories:** Developer tools, Automation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 parsed e-invoices

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## XRechnung & ZUGFeRD / Factur-X E-Invoice Parser – XML/PDF to JSON

Turn German and EU **e-invoices** into clean, flat **JSON** in seconds. Give the actor links to **XRechnung** XML files (UBL or CII) or **ZUGFeRD / Factur-X** PDFs – it extracts the embedded XML from the PDF automatically, detects the format and profile, and returns one row per invoice with seller, buyer, Leitweg-ID, IBAN/BIC, payment terms, totals, VAT breakdown, line items and plausibility warnings.

**Price: $0.003 per successfully parsed invoice** ($3 per 1,000). Files that fail to download or parse are free.

### Who is it for?

- **Accounts payable & bookkeeping** teams that receive XRechnung / ZUGFeRD invoices and want the data in a spreadsheet, ERP, DATEV pipeline or database
- **Developers & automation builders** (n8n, Make, Zapier, AI agents) who need one stable JSON schema instead of two XML syntaxes and dozens of profiles
- **SaaS tools, tax advisors and auditors** who want to bulk-read invoice archives and spot calculation errors
- **AI / LLM workflows** – the output is flat and self-describing, ideal for agents via MCP

### What it does

| Feature | Details |
|---|---|
| Supported formats | XRechnung UBL (Invoice + CreditNote), XRechnung CII, ZUGFeRD 2.x / Factur-X (MINIMUM, BASIC WL, BASIC, EN16931, EXTENDED, XRECHNUNG), generic EN 16931 / Peppol UBL |
| PDF support | Extracts `factur-x.xml`, `zugferd-invoice.xml` or `xrechnung.xml` from hybrid PDFs (pypdf, BSD licence) |
| Unified schema | Same field names for UBL and CII – no XPath needed |
| Plausibility checks | Sum of lines vs. line total (BR-CO-10), line total ± allowances/charges = tax basis (BR-CO-13), tax basis + VAT = grand total (BR-CO-15), grand total − prepaid = amount due (BR-CO-16), VAT breakdown sums and rates, required EN 16931 fields, XRechnung Leitweg-ID / seller e-mail / payment means |
| Safe XML parsing | defusedxml – protects against XXE and entity-expansion attacks |
| Fast & cheap | 3 invoices in ~3 seconds on 256 MB, no browser, no proxy |

> **Important:** This is a fast **parser with plausibility checks**, **not a certified validator**. It does not run the official KoSIT validator / EN 16931 Schematron rules. For legally binding conformance checks use the [KoSIT validator](https://github.com/itplr-kosit/validator).

### Why this actor?

- **One schema for everything** – XRechnung UBL, XRechnung CII and ZUGFeRD/Factur-X come out identical.
- **Cheaper than alternatives** – most e-invoice actors in the Store charge $0.008–$0.04 per document; this one costs $0.003 and failed files are free.
- **Ready for automation** – flat numbers (not strings), ISO dates, nested `seller` / `buyer` objects, `validationWarnings` list for alerting.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `fileUrls` | array of URLs | 3 public sample invoices | Direct links to XML or PDF e-invoices (public or presigned URLs, e.g. S3, Google Cloud Storage, Apify key-value store records) |
| `includeLineItems` | boolean | `true` | Adds the `lineItems` array |
| `includeRawXml` | boolean | `false` | Adds the complete invoice XML as `rawXml` |

```json
{
  "fileUrls": [
    "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml",
    "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/02.01a-INVOICE_uncefact.xml",
    "https://raw.githubusercontent.com/ZUGFeRD/mustangproject/master/library/src/test/resources/EN16931_Einfach.pdf"
  ],
  "includeLineItems": true,
  "includeRawXml": false
}
```

The default samples come from the official [XRechnung test suite](https://github.com/itplr-kosit/xrechnung-testsuite) (KoSIT) and the [Mustangproject](https://github.com/ZUGFeRD/mustangproject) ZUGFeRD library.

### Output

Real result for the ZUGFeRD sample PDF (`EN16931_Einfach.pdf`, shortened):

```json
{
  "fileUrl": "https://raw.githubusercontent.com/ZUGFeRD/mustangproject/master/library/src/test/resources/EN16931_Einfach.pdf",
  "status": "ok",
  "format": "ZUGFeRD/Factur-X",
  "syntax": "CII",
  "profile": "EN16931",
  "invoiceNumber": "471102",
  "issueDate": "2024-11-15",
  "typeCode": "380",
  "typeName": "Commercial invoice",
  "currency": "EUR",
  "seller": {
    "name": "Lieferant GmbH",
    "vatId": "DE123456789",
    "taxNumber": "201/113/40209",
    "street": "Lieferantenstraße 20",
    "postalCode": "80333",
    "city": "München",
    "country": "DE"
  },
  "buyer": { "name": "Kunden AG Mitte", "id": "GE2020211", "city": "Frankfurt", "country": "DE" },
  "paymentTerms": "Zahlbar innerhalb 30 Tagen netto bis 15.12.2024, 3% Skonto innerhalb 10 Tagen bis 25.11.2024",
  "lineTotal": 473.0,
  "taxBasis": 473.0,
  "taxTotal": 56.87,
  "grandTotal": 529.87,
  "prepaid": 0.0,
  "payableAmount": 529.87,
  "vatBreakdown": [
    { "category": "S", "rate": 7.0, "taxable": 275.0, "tax": 19.25 },
    { "category": "S", "rate": 19.0, "taxable": 198.0, "tax": 37.62 }
  ],
  "lineItems": [
    { "id": "1", "name": "Trennblätter A4", "sellerItemId": "TB100A4", "quantity": 20.0, "unit": "H87", "netPrice": 9.9, "lineTotal": 198.0, "vatCategory": "S", "vatRate": 19.0 },
    { "id": "2", "name": "Joghurt Banane", "sellerItemId": "ARNR2", "quantity": 50.0, "unit": "H87", "netPrice": 5.5, "lineTotal": 275.0, "vatCategory": "S", "vatRate": 7.0 }
  ],
  "sourceType": "PDF",
  "pdfAttachmentName": "factur-x.xml",
  "lineItemCount": 2,
  "validationWarnings": [],
  "validationWarningCount": 0
}
```

The XRechnung samples from the same run: `XRechnung-UBL` invoice `123456XX`, Leitweg-ID `04011000-12345-03`, IBAN `DE79000000001234567890`, grand total 336.90 EUR; `XRechnung-CII` invoice `1234567`, Leitweg-ID `90000000-03083-72`, grand total 12,829.69 EUR – all with 0 warnings.

#### All output fields

`fileUrl`, `status` (`ok` / `error`), `error`, `format` (XRechnung-UBL, XRechnung-CII, ZUGFeRD/Factur-X, UBL (EN 16931 / Peppol)), `syntax`, `profile`, `specificationId`, `documentType`, `invoiceNumber`, `issueDate`, `dueDate`, `typeCode`, `typeName`, `currency`, `buyerReference` (Leitweg-ID), `orderReference`, `contractReference`, `notes`, `seller` / `buyer` {name, tradingName, id, vatId, taxNumber, legalRegistrationId, street, postalCode, city, country, email, phone, contactName, electronicAddress}, `paymentTerms`, `paymentMeansCode`, `iban`, `bic`, `accountName`, `lineTotal`, `allowanceTotal`, `chargeTotal`, `taxBasis`, `taxTotal`, `grandTotal`, `prepaid`, `roundingAmount`, `payableAmount`, `vatBreakdown`, `lineItems`, `lineItemCount`, `sourceType`, `pdfAttachmentName`, `validationWarnings`, `validationWarningCount`, `rawXml` (optional).

Empty fields are omitted inside `seller`, `buyer` and line items.

### Pricing

Pay per event: **$0.003 per successfully parsed invoice**. Download errors, PDFs without XML, and non-invoice files cost nothing (only the tiny platform start fee). 1,000 invoices ≈ $3.

### Use via API, n8n, Make or AI agents

**API (sync, returns the dataset items):**

```bash
curl -X POST "https://api.apify.com/v2/acts/fast_data_asap~xrechnung-zugferd-einvoice-parser/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fileUrls": ["https://example.com/invoice.pdf"]}'
```

**Python:**

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_TOKEN")
run = client.actor("fast_data_asap/xrechnung-zugferd-einvoice-parser").call(run_input={"fileUrls": ["https://example.com/rechnung.xml"]})
for inv in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(inv["invoiceNumber"], inv.get("grandTotal"), inv.get("validationWarnings"))
```

**n8n / Make / Zapier:** use the Apify node, action "Run Actor and get dataset items", actor `fast_data_asap/xrechnung-zugferd-einvoice-parser`.

**MCP (Claude, Cursor, other AI agents):** `https://mcp.apify.com?tools=fast_data_asap/xrechnung-zugferd-einvoice-parser`

### Limitations

- Not a certified KoSIT / EN 16931 validator – plausibility checks only.
- ZUGFeRD 1.0 (`CrossIndustryDocument`) is not supported; ZUGFeRD 2.x, Factur-X and XRechnung are.
- Files must be reachable via URL (no login). Encrypted PDFs may fail.

### Kurzfassung auf Deutsch

**XRechnung- und ZUGFeRD-Rechnungen automatisch auslesen.** Seit dem **1. Januar 2025** müssen alle Unternehmen in Deutschland E-Rechnungen im B2B-Bereich **empfangen** können (Wachstumschancengesetz); die Pflicht zum Versand folgt schrittweise bis 2028. Dieser Actor liest XRechnung (UBL und CII) sowie ZUGFeRD-/Factur-X-PDFs (eingebettetes XML wird automatisch extrahiert) und liefert sauberes JSON: Rechnungsnummer, Datum, Fälligkeit, Verkäufer und Käufer inkl. USt-IdNr. und Steuernummer, Leitweg-ID, IBAN/BIC, Zahlungsbedingungen, Summen, USt-Aufschlüsselung und Rechnungspositionen – plus Plausibilitätsprüfungen (Summen, Steuerbeträge, Pflichtfelder). **Kein zertifizierter KoSIT-Validator.** Preis: 0,003 $ pro erfolgreich gelesener Rechnung, fehlerhafte Dateien sind kostenlos.

# Actor input Schema

## `fileUrls` (type: `array`):

Direct links to XRechnung XML (UBL or CII), ZUGFeRD / Factur-X PDFs or plain CII XML files. Upload your own files to any public/presigned URL, e.g. an Apify key-value store record.

## `includeLineItems` (type: `boolean`):

Adds every invoice line (id, name, quantity, unit, net price, line total, VAT rate).

## `includeRawXml` (type: `boolean`):

Adds the full invoice XML (also the XML extracted from a PDF) as a text field.

## Actor input object example

```json
{
  "fileUrls": [
    "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml",
    "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/02.01a-INVOICE_uncefact.xml",
    "https://raw.githubusercontent.com/ZUGFeRD/mustangproject/master/library/src/test/resources/EN16931_Einfach.pdf"
  ],
  "includeLineItems": true,
  "includeRawXml": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "fileUrls": [
        "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml",
        "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/02.01a-INVOICE_uncefact.xml",
        "https://raw.githubusercontent.com/ZUGFeRD/mustangproject/master/library/src/test/resources/EN16931_Einfach.pdf"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("fast_data_asap/xrechnung-zugferd-einvoice-parser").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "fileUrls": [
        "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml",
        "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/02.01a-INVOICE_uncefact.xml",
        "https://raw.githubusercontent.com/ZUGFeRD/mustangproject/master/library/src/test/resources/EN16931_Einfach.pdf",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("fast_data_asap/xrechnung-zugferd-einvoice-parser").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "fileUrls": [
    "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/01.01a-INVOICE_ubl.xml",
    "https://raw.githubusercontent.com/itplr-kosit/xrechnung-testsuite/master/src/test/business-cases/standard/02.01a-INVOICE_uncefact.xml",
    "https://raw.githubusercontent.com/ZUGFeRD/mustangproject/master/library/src/test/resources/EN16931_Einfach.pdf"
  ]
}' |
apify call fast_data_asap/xrechnung-zugferd-einvoice-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fast_data_asap/xrechnung-zugferd-einvoice-parser"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/xW5PdpTfrBTfwNTj0/builds/gGKBZv3iODCIMbUmi/openapi.json