Available

Parser API

Extract structured data from e-invoices. Convert complex XML structures into easy-to-process JSON - supports 37 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: application/json
Body: data (e-invoice file, base64 encoded, XML or PDF — required) plus optional filename

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)

Every parse route

65 country/format combinations across 37 countries, generated from the OpenAPI spec. The auto-detect route needs none of them.

Auto-Detect

/api/v1/invoice/parse

Germany (DE)

/api/v1/invoice/de/xrechnung/parseXRechnung
/api/v1/invoice/de/zugferd/parseZUGFeRD

Austria (AT)

/api/v1/invoice/at/cii/parseCII
/api/v1/invoice/at/ebinterface/parseebInterface
/api/v1/invoice/at/ubl/parseUBL
/api/v1/invoice/at/zugferd/parseZUGFeRD

Switzerland (CH)

/api/v1/invoice/ch/cii/parseCII
/api/v1/invoice/ch/ubl/parseUBL
/api/v1/invoice/ch/zugferd/parseZUGFeRD

France (FR)

/api/v1/invoice/fr/cii/parseCII
/api/v1/invoice/fr/facturx/parseFactur-X
/api/v1/invoice/fr/ubl/parseUBL

Italy (IT)

/api/v1/invoice/it/cii/parseCII
/api/v1/invoice/it/fatturapa/parseFatturaPA
/api/v1/invoice/it/ubl/parseUBL

Spain (ES)

/api/v1/invoice/es/cii/parseCII
/api/v1/invoice/es/facturae/parseFacturae
/api/v1/invoice/es/ubl/parseUBL

Netherlands (NL)

/api/v1/invoice/nl/cii/parseCII
/api/v1/invoice/nl/ubl/parseUBL

Belgium (BE)

/api/v1/invoice/be/cii/parseCII
/api/v1/invoice/be/facturx/parseFactur-X
/api/v1/invoice/be/ubl/parseUBL

Poland (PL)

/api/v1/invoice/pl/ksef/parseKSeF
/api/v1/invoice/pl/peppol-ubl/parsePeppol UBL
/api/v1/invoice/pl/ubl/parseUBL

Portugal (PT)

/api/v1/invoice/pt/peppol-ubl/parsePeppol UBL
/api/v1/invoice/pt/saft/parseSAF-T
/api/v1/invoice/pt/ubl/parseUBL

United Arab Emirates (AE)

/api/v1/invoice/ae/ubl/parseUBL

Australia (AU)

/api/v1/invoice/au/ubl/parseUBL

Bulgaria (BG)

/api/v1/invoice/bg/cii/parseCII
/api/v1/invoice/bg/ubl/parseUBL

Cyprus (CY)

/api/v1/invoice/cy/ubl/parseUBL

Czech Republic (CZ)

/api/v1/invoice/cz/isdoc/parseISDOC
/api/v1/invoice/cz/ubl/parseUBL

Denmark (DK)

/api/v1/invoice/dk/ubl/parseUBL

Estonia (EE)

/api/v1/invoice/ee/ubl/parseUBL

Finland (FI)

/api/v1/invoice/fi/ubl/parseUBL

United Kingdom (GB)

/api/v1/invoice/gb/ubl/parseUBL

Greece (GR)

/api/v1/invoice/gr/mydata/parsemyDATA
/api/v1/invoice/gr/ubl/parseUBL

Croatia (HR)

/api/v1/invoice/hr/peppol-ubl/parsePeppol UBL
/api/v1/invoice/hr/ubl/parseUBL

Hungary (HU)

/api/v1/invoice/hu/nav/parseNAV
/api/v1/invoice/hu/ubl/parseUBL

Ireland (IE)

/api/v1/invoice/ie/ubl/parseUBL

Iceland (IS)

/api/v1/invoice/is/ubl/parseUBL

Japan (JP)

/api/v1/invoice/jp/ubl/parseUBL

Liechtenstein (LI)

/api/v1/invoice/li/ubl/parseUBL

Lithuania (LT)

/api/v1/invoice/lt/ubl/parseUBL

Luxembourg (LU)

/api/v1/invoice/lu/ubl/parseUBL

Latvia (LV)

/api/v1/invoice/lv/ubl/parseUBL

Malta (MT)

/api/v1/invoice/mt/ubl/parseUBL

Norway (NO)

/api/v1/invoice/no/ubl/parseUBL

New Zealand (NZ)

/api/v1/invoice/nz/ubl/parseUBL

Oman (OM)

/api/v1/invoice/om/ubl/parseUBL

Romania (RO)

/api/v1/invoice/ro/cii/parseCII
/api/v1/invoice/ro/efactura/parsee-Factura
/api/v1/invoice/ro/peppol-ubl/parsePeppol UBL
/api/v1/invoice/ro/ubl/parseUBL

Sweden (SE)

/api/v1/invoice/se/ubl/parseUBL

Slovenia (SI)

/api/v1/invoice/si/ubl/parseUBL

Slovakia (SK)

/api/v1/invoice/sk/peppol-ubl/parsePeppol UBL
/api/v1/invoice/sk/ubl/parseUBL

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: application/json' \
4  -d '{
5    "data": "'$(base64 -i rechnung.xml)'",
6    "filename": "rechnung.xml"
7  }'

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      "countryCode": "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      "countryCode": "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        "netAmount": 1500.00,
54        "taxAmount": 285.00
55      }
56    ],
57    "paymentTerms": {
58      "dueDays": 30,
59      "description": "Zahlbar innerhalb von 30 Tagen"
60    },
61    "notes": "Vielen Dank für Ihren Auftrag!"
62  },
63  "detection": {
64    "format": "XRECHNUNG_UBL",
65    "formatVersion": "3.0.2",
66    "countryCode": "DE",
67    "confidence": 98,
68    "formatMethod": "NAMESPACE",
69    "countrySource": "DOCUMENT",
70    "isAmbiguous": false,
71    "alternativeCountries": []
72  },
73  "hash": "9f2c1b7d4e8a03f5c6b9d0e1a2f3c4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
74  "errors": [],
75  "warnings": []
76}

Detection Object Fields

format

Detected format (XRECHNUNG_UBL, XRECHNUNG_CII, ZUGFERD_EN16931, FACTUR_X_EN16931, FATTURAPA, …)

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: NAMESPACE, ROOT_ELEMENT, CUSTOMIZATION_ID, PROFILE_ID or HEURISTIC

countrySource

Source of country detection: DOCUMENT, FORMAT_MAPPING or UNKNOWN

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      "countryCode": "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      "countryCode": "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        "netAmount": 1500.00,
54        "taxAmount": 285.00
55      }
56    ],
57    "paymentTerms": {
58      "dueDays": 30,
59      "description": "Zahlbar innerhalb von 30 Tagen"
60    },
61    "notes": "Vielen Dank für Ihren Auftrag!"
62  },
63  "format": "XRECHNUNG_UBL",
64  "hash": "9f2c1b7d4e8a03f5c6b9d0e1a2f3c4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
65  "errors": [],
66  "warnings": []
67}

Error Responses

400 Bad Request

json

1{
2  "success": false,
3  "detection": {
4    "format": null,
5    "countryCode": null,
6    "confidence": 12,
7    "formatMethod": "HEURISTIC",
8    "countrySource": "UNKNOWN",
9    "isAmbiguous": false,
10    "alternativeCountries": []
11  },
12  "error": "FORMAT_NOT_DETECTED",
13  "message": "Could not reliably detect the document format. Please use the explicit parse endpoint with country and format parameters."
14}

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": "Usage limit reached for xrechnung:de:parse",
4  "quota": {
5    "current": 100,
6    "limit": 100,
7    "period": "monthly"
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

XRechnungZUGFeRD

ATAustria

CIIebInterfaceUBLZUGFeRD

CHSwitzerland

CIIUBLZUGFeRD

FRFrance

CIIFactur-XUBL

ITItaly

CIIFatturaPAUBL

ESSpain

CIIFacturaeUBL

NLNetherlands

CIIUBL

BEBelgium

CIIFactur-XUBL

PLPoland

KSeFPeppol UBLUBL

PTPortugal

Peppol UBLSAF-TUBL

AEUnited Arab Emirates

UBL

AUAustralia

UBL

BGBulgaria

CIIUBL

CYCyprus

UBL

CZCzech Republic

ISDOCUBL

DKDenmark

UBL

EEEstonia

UBL

FIFinland

UBL

GBUnited Kingdom

UBL

GRGreece

myDATAUBL

HRCroatia

Peppol UBLUBL

HUHungary

NAVUBL

IEIreland

UBL

ISIceland

UBL

JPJapan

UBL

LILiechtenstein

UBL

LTLithuania

UBL

LULuxembourg

UBL

LVLatvia

UBL

MTMalta

UBL

NONorway

UBL

NZNew Zealand

UBL

OMOman

UBL

RORomania

CIIe-FacturaPeppol UBLUBL

SESweden

UBL

SISlovenia

UBL

SKSlovakia

Peppol UBLUBL

= Available

Features

XML to JSON

Extract structured JSON data from XRechnung, ZUGFeRD and UBL XML

All Formats

XRechnung, ZUGFeRD, Factur-X, FatturaPA, Facturae, ebInterface, UBL, Peppol UBL, CII and the national formats KSeF, SAF-T, ISDOC, NAV, myDATA and e-Factura

PDF Extraction

Automatically extract embedded XML from ZUGFeRD/Factur-X PDFs

37 Countries

Support for AE, AT, AU, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, JP, LI, LT, LU, LV, MT, NL, NO, NZ, OM, PL, PT, RO, SE, SI, SK

Normalized Schema

Unified JSON schema regardless of source format

One document per request

The parse body takes exactly one data field; for batches call the endpoint once per document

More APIs

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

More APIs

Field reference

Every field of the invoice object with type and required flag

Creator API

Create invoices

Validator API

Validate invoices

Converter API

Convert formats

Changelog

Latest updates