Available

Parser API

Extract structured data from e-invoices. Convert complex XML structures into easy-to-process JSON - supports 28 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: application/json
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 (Germany)

/api/v1/invoice/de/facturx/parse

UBL (Germany)

/api/v1/invoice/de/ubl/parse

ebInterface (Austria)

/api/v1/invoice/at/ebinterface/parse

ZUGFeRD (Austria)

/api/v1/invoice/at/zugferd/parse

Factur-X (France)

/api/v1/invoice/fr/facturx/parse

UBL (France)

/api/v1/invoice/fr/ubl/parse

FatturaPA (Italy)

/api/v1/invoice/it/fatturapa/parse

Facturae (Spain)

/api/v1/invoice/es/facturae/parse

UBL (Netherlands)

/api/v1/invoice/nl/ubl/parse

UBL (Belgium)

/api/v1/invoice/be/ubl/parse

SAF-T (Portugal)

/api/v1/invoice/pt/saft/parse

KSeF (Poland)

/api/v1/invoice/pl/ksef/parse

ISDOC (Czech Republic)

/api/v1/invoice/cz/isdoc/parse

NAV (Hungary)

/api/v1/invoice/hu/nav/parse

eFactura (Romania)

/api/v1/invoice/ro/efactura/parse

UBL (Romania)

/api/v1/invoice/ro/ubl/parse

UBL (Bulgaria)

/api/v1/invoice/bg/ubl/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: 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",
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": "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      "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": "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.0.2ZUGFERD 2.4FACTUR-XUBL

ATAustria

EBINTERFACEZUGFERD

CHSwitzerland

QR-BILLCIIUBL

FRFrance

FACTUR-XUBL

ITItaly

FATTURAPA

ESSpain

FACTURAE

NLNetherlands

UBL

BEBelgium

UBL

PTPortugal

SAF-TPeppol UBL

PLPoland

KSeFPeppol UBL

CZCzech Republic

ISDOCUBL

HUHungary

NAVUBL

RORomania

EFACTURAPeppol UBLUBL

BGBulgaria

UBL

SESweden

Peppol UBL

NONorway

Peppol UBL

DKDenmark

Peppol UBL

FIFinland

Peppol UBL

IEIreland

Peppol UBL

GBUnited Kingdom

Peppol UBL

LULuxembourg

Peppol UBL

MTMalta

Peppol UBL

CYCyprus

Peppol UBL

SISlovenia

Peppol UBL

EEEstonia

Peppol UBL

LVLatvia

Peppol UBL

LTLithuania

Peppol UBL

GRGreece

myDATAPeppol UBL

= Available

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

28 Countries

Support for DE, AT, CH, FR, IT, ES, NL, BE, PT, PL, CZ, HU, RO, BG, SE, NO, DK, FI, IE, GB, LU, MT, CY, SI, EE, LV, LT, GR

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