Available

Parser API

Extract structured data from e-invoices. Convert complex XML structures into easy-to-process JSON - supports 14 European countries.

Production Ready

Endpoints

POST/api/v1/invoice/parseAuto-Detect

Automatically detects the e-invoice format and country, then parses the document. The country is primarily extracted from document content (seller address).

Request

Content-Type: multipart/form-data
Body: file (e-invoice file as XML or PDF)

This endpoint additionally returns a detection object with format detection information (format, version, confidence score).

POST/api/v1/invoice/{countryCode}/{format}/parse

Parses an e-invoice with explicit country and format specification. Use this endpoint when you already know the format and want to skip auto-detection.

Path Parameters

countryCode

required

ISO 3166-1 Alpha-2 Ländercode (z.B. DE, AT, FR)

format

required

Format-Identifier (z.B. XRECHNUNG, ZUGFERD, FACTURX)

XRechnung (Germany)

/api/v1/invoice/DE/XRECHNUNG/parse

ZUGFeRD (Germany)

/api/v1/invoice/DE/ZUGFERD/parse

Factur-X (France)

/api/v1/invoice/FR/FACTURX/parse

FatturaPA (Italy)

/api/v1/invoice/IT/FATTURAPA/parse

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer sk_test_xxx

sk_test_*

Test keys for development and testing

sk_live_*

Live keys for production environment

Code Examples

Automatic detection of format and country from the document.

bash

1curl -X POST 'https://service.invoice-api.xhub.io/api/v1/invoice/parse' \
2  -H 'Authorization: Bearer sk_test_xxx' \
3  -H 'Content-Type: multipart/form-data' \
4  -F 'file=@rechnung.xml'

Response Schema

The API returns a normalized JSON schema, regardless of the source format.

Auto-DetectResponse with Detection Object

The Auto-Detect endpoint ( /api/v1/invoice/parse ) additionally returns a detection object with information about automatic format detection.

json

1{
2  "success": true,
3  "invoice": {
4    "invoiceNumber": "RE-2025-001",
5    "type": "invoice",
6    "issueDate": "2025-01-15",
7    "dueDate": "2025-02-15",
8    "deliveryDate": "2025-01-10",
9    "seller": {
10      "name": "Meine Firma GmbH",
11      "street": "Musterstraße 1",
12      "city": "Berlin",
13      "postalCode": "10115",
14      "country": "DE",
15      "taxId": "DE123456789",
16      "vatId": "DE123456789",
17      "email": "rechnung@meinefirma.de",
18      "phone": "+49 30 12345678"
19    },
20    "buyer": {
21      "name": "Kunde AG",
22      "street": "Kundenweg 42",
23      "city": "München",
24      "postalCode": "80331",
25      "country": "DE",
26      "taxId": "DE987654321",
27      "vatId": "DE987654321",
28      "email": "einkauf@kunde.de",
29      "phone": "+49 89 87654321"
30    },
31    "items": [
32      {
33        "position": 1,
34        "description": "Softwarelizenz Enterprise",
35        "articleNumber": "SW-ENT-001",
36        "quantity": 1,
37        "unit": "C62",
38        "unitPrice": 1500.00,
39        "taxRate": 19,
40        "taxCategoryCode": "S",
41        "netAmount": 1500.00,
42        "taxAmount": 285.00,
43        "grossAmount": 1785.00
44      }
45    ],
46    "currency": "EUR",
47    "subtotal": 1500.00,
48    "total": 1785.00,
49    "taxSummary": [
50      {
51        "taxRate": 19,
52        "taxCategoryCode": "S",
53        "taxableAmount": 1500.00,
54        "taxAmount": 285.00
55      }
56    ],
57    "paymentTerms": {
58      "dueDate": "2025-02-15",
59      "paymentTermsText": "Zahlbar innerhalb von 30 Tagen"
60    },
61    "notes": "Vielen Dank für Ihren Auftrag!"
62  },
63  "detection": {
64    "format": "XRECHNUNG",
65    "formatVersion": "3.0.2",
66    "countryCode": "DE",
67    "confidence": 98,
68    "formatMethod": "namespace_analysis",
69    "countrySource": "seller_address",
70    "isAmbiguous": false,
71    "alternativeCountries": []
72  },
73  "hash": "sha256:a1b2c3d4e5f6...",
74  "errors": [],
75  "warnings": []
76}

Detection Object Fields

format

Detected format (XRECHNUNG, ZUGFERD, FACTURX, ...)

formatVersion

Detected format version (e.g. "3.0.2")

countryCode

Detected country code (ISO 3166-1 Alpha-2)

confidence

Detection confidence (0-100)

formatMethod

Format detection method (e.g. "namespace_analysis")

countrySource

Source of country detection (e.g. "seller_address")

isAmbiguous

Whether the detection was ambiguous

alternativeCountries

Alternative countries in case of ambiguous detection

Response for Format-specific Endpoint

The format-specific endpoint ( /api/v1/invoice/{countryCode}/{format}/parse ) returns the same response, but without the detection object.

json

1{
2  "success": true,
3  "invoice": {
4    "invoiceNumber": "RE-2025-001",
5    "type": "invoice",
6    "issueDate": "2025-01-15",
7    "dueDate": "2025-02-15",
8    "deliveryDate": "2025-01-10",
9    "seller": {
10      "name": "Meine Firma GmbH",
11      "street": "Musterstraße 1",
12      "city": "Berlin",
13      "postalCode": "10115",
14      "country": "DE",
15      "taxId": "DE123456789",
16      "vatId": "DE123456789",
17      "email": "rechnung@meinefirma.de",
18      "phone": "+49 30 12345678"
19    },
20    "buyer": {
21      "name": "Kunde AG",
22      "street": "Kundenweg 42",
23      "city": "München",
24      "postalCode": "80331",
25      "country": "DE",
26      "taxId": "DE987654321",
27      "vatId": "DE987654321",
28      "email": "einkauf@kunde.de",
29      "phone": "+49 89 87654321"
30    },
31    "items": [
32      {
33        "position": 1,
34        "description": "Softwarelizenz Enterprise",
35        "articleNumber": "SW-ENT-001",
36        "quantity": 1,
37        "unit": "C62",
38        "unitPrice": 1500.00,
39        "taxRate": 19,
40        "taxCategoryCode": "S",
41        "netAmount": 1500.00,
42        "taxAmount": 285.00,
43        "grossAmount": 1785.00
44      }
45    ],
46    "currency": "EUR",
47    "subtotal": 1500.00,
48    "total": 1785.00,
49    "taxSummary": [
50      {
51        "taxRate": 19,
52        "taxCategoryCode": "S",
53        "taxableAmount": 1500.00,
54        "taxAmount": 285.00
55      }
56    ],
57    "paymentTerms": {
58      "dueDate": "2025-02-15",
59      "paymentTermsText": "Zahlbar innerhalb von 30 Tagen"
60    },
61    "notes": "Vielen Dank für Ihren Auftrag!"
62  },
63  "format": "XRECHNUNG_3.0.2",
64  "hash": "sha256:a1b2c3d4e5f6...",
65  "errors": [],
66  "warnings": []
67}

Error Responses

400 Bad Request

json

1{
2  "error": "BAD_REQUEST",
3  "message": "Invalid file format or malformed request"
4}

401 Unauthorized

json

1{
2  "error": "UNAUTHORIZED",
3  "message": "Invalid or missing API key"
4}

403 Forbidden

json

1{
2  "error": "FORBIDDEN",
3  "message": "Your API key does not have permission for this operation"
4}

429 Quota Exceeded

json

1{
2  "error": "QUOTA_EXCEEDED",
3  "message": "Monthly quota exceeded",
4  "quota": {
5    "limit": 100,
6    "used": 100,
7    "resetsAt": "2025-02-01T00:00:00Z"
8  }
9}

500 Internal Server Error

json

1{
2  "error": "INTERNAL_ERROR",
3  "message": "An unexpected error occurred"
4}

Supported Countries & Formats

For the format-specific endpoint use these combinations of countryCode and format.

DEGermany

XRECHNUNG 3.0ZUGFERD 2.3

ATAustria

EBINTERFACE

CHSwitzerland

QR-BILL

FRFrance

FACTUR-X

ITItaly

FATTURAPA

ESSpain

FACTURAE

NLNetherlands

UBL

BEBelgium

UBL

PTPortugalQ2.2026

CIUS-PTUBL

PLPolandQ2.2026

KSEFUBL

CZCzech RepublicQ2.2026

ISDOCUBL

HUHungaryQ2.2026

NAVUBL

RORomaniaQ2.2026

EFACTURAUBL

BGBulgariaQ2.2026

UBLCII

= Available | Q2.2026 = Planned

Features

XML to JSON

Extract structured JSON data from XRechnung, ZUGFeRD and UBL XML

All Formats

Support for XRechnung 2.x/3.x, ZUGFeRD 2.x, Factur-X, UBL

PDF Extraction

Automatically extract embedded XML from ZUGFeRD/Factur-X PDFs

14 Countries

Support for DE, [Q2.2026 AT, CH, FR, IT, ES, NL, BE, PT, PL, CZ, HU, RO, BG]

Normalized Schema

Unified JSON schema regardless of source format

Batch Processing

Process multiple invoices in a single request

More APIs

Combine the Parser API with the Validator API for validation or the Creator API for creating e-invoices.

More APIs

Creator API

Create invoices

Validator API

Validate invoices

Converter API

Convert formats

Changelog

Latest updates