Core API

Invoice Creator API

Create e-invoices in various formats for 14 European countries. Supports XRechnung, ZUGFeRD, Factur-X, FatturaPA and many more.

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

Example: POST /api/v1/invoice/DE/XRECHNUNG/generate

Authentication

The API uses Bearer Token authentication. Add your API key in the Authorization header:

bash

1Authorization: Bearer sk_live_abc123...

sk_test_* - Test mode (no real invoices, unlimited requests)

sk_live_* - Live mode (production invoices, billed)

Example

bash

1curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/DE/XRECHNUNG/generate \
2  -H "Authorization: Bearer sk_live_abc123..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "invoiceNumber": "RE-2025-001",
6    "type": "invoice",
7    "issueDate": "2025-01-15",
8    "dueDate": "2025-02-15",
9    "currency": "EUR",
10    "seller": {
11      "name": "Meine Firma GmbH",
12      "street": "Musterstraße 1",
13      "city": "Berlin",
14      "postalCode": "10115",
15      "country": "DE",
16      "taxId": "123/456/78901",
17      "vatId": "DE123456789",
18      "email": "rechnung@meinefirma.de",
19      "phone": "+49 30 1234567"
20    },
21    "buyer": {
22      "name": "Kunde AG",
23      "street": "Kundenweg 42",
24      "city": "München",
25      "postalCode": "80331",
26      "country": "DE",
27      "vatId": "DE987654321",
28      "email": "einkauf@kunde.de"
29    },
30    "items": [
31      {
32        "position": 1,
33        "description": "Beratungsleistung",
34        "articleNumber": "CONS-001",
35        "quantity": 10,
36        "unit": "HUR",
37        "unitPrice": 150.00,
38        "taxRate": 19,
39        "taxCategoryCode": "S",
40        "netAmount": 1500.00,
41        "taxAmount": 285.00,
42        "grossAmount": 1785.00
43      }
44    ],
45    "paymentTerms": {
46      "dueDate": "2025-02-15",
47      "paymentTermsText": "Zahlbar innerhalb von 30 Tagen ohne Abzug"
48    },
49    "notes": "Vielen Dank für Ihren Auftrag!"
50  }'

Response

On success you will receive 200 OK with the created invoice object:

json

1{
2  "success": true,
3  "format": "XRECHNUNG",
4  "filename": "RE-2025-001.xml",
5  "mimeType": "application/xml",
6  "hash": "a1b2c3d4e5f6789...sha256hash",
7  "data": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...base64encoded...",
8  "errors": [],
9  "warnings": [
10    {
11      "code": "W001",
12      "message": "Optionales Feld 'buyerReference' nicht gesetzt",
13      "field": "buyer.reference"
14    }
15  ]
16}

Response Fields

Field	Type	Description
`success`	boolean	Indicates whether the invoice was successfully created
`format`	string	The generated format (e.g. XRECHNUNG, ZUGFERD)
`filename`	string	Suggested filename for the invoice
`mimeType`	string	MIME type of the generated file (e.g. application/xml, application/pdf)
`hash`	string	SHA-256 hash of the generated document
`data`	string	Base64-encoded invoice data
`errors`	array	List of errors (code, message, field)
`warnings`	array	List of warnings (code, message, field)

Request Parameters

Path Parameters

Parameter	Type	Description
`countryCode`required	string	ISO 3166-1 alpha-2 Ländercode: `DE`, `AT`, `CH`, `FR`, `IT`, `ES`, `NL`, `BE`, PT, PL, CZ, HU, RO, BG
`format`required	string	Zielformat: `PDF`, `XRECHNUNG`, `ZUGFERD`, `FACTURX`, `FATTURAPA`, `FACTURAE`, `UBL`, `EBINTERFACE`, `QRBILL`, ISDOC, NAV

XRechnung (Germany)

/api/v1/invoice/DE/XRECHNUNG/generate

ZUGFeRD (Germany)

/api/v1/invoice/DE/ZUGFERD/generate

Factur-X (France)

/api/v1/invoice/FR/FACTURX/generate

FatturaPA (Italy)

/api/v1/invoice/IT/FATTURAPA/generate

ebInterface (Austria)

/api/v1/invoice/AT/EBINTERFACE/generate

PDF (alle Länder)

/api/v1/invoice/DE/PDF/generate

Body Parameters

Parameter	Type	Required	Description
`invoiceNumber`	string		Unique invoice number of the issuer
`type`	string	-	Document type: "invoice" \| "credit_note" \| "proforma" \| "correction". Default: "invoice"
`issueDate`	string		Invoice date in YYYY-MM-DD format
`dueDate`	string	-	Due date in YYYY-MM-DD format
`deliveryDate`	string	-	Delivery or service date in YYYY-MM-DD format
`seller`	object		Seller/invoice issuer (details below)
`buyer`	object		Buyer/invoice recipient (details below)
`items`	array		Invoice line items (at least 1)
`currency`	string	-	Currency code (ISO 4217). Default: EUR
`subtotal`	number	-	Net total (automatically calculated if not provided)
`total`	number	-	Gross total (automatically calculated if not provided)
`taxSummary`	array	-	Tax summary by tax rates (automatically calculated)
`paymentTerms`	object	-	Payment terms (dueDate, paymentTermsText)
`notes`	string	-	Free-text note on the invoice

seller (Seller)

Parameter	Type	Required	Description
`name`	string		Company name
`street`	string		Street and house number
`city`	string		City
`postalCode`	string		Postal code
`country`	string		Country code (ISO 3166-1 alpha-2)
`taxId`	string	-	Tax ID
`vatId`	string	-	VAT ID (e.g. DE123456789)
`email`	string	-	Email address
`phone`	string	-	Phone number

buyer (Buyer)

Parameter	Type	Required	Description
`name`	string		Company name
`street`	string		Street and house number
`city`	string		City
`postalCode`	string		Postal code
`country`	string		Country code (ISO 3166-1 alpha-2)
`taxId`	string	-	Buyer tax ID
`vatId`	string	-	Buyer VAT ID
`email`	string	-	Email address
`phone`	string	-	Phone number

items[] (Line Items)

Parameter	Type	Required	Description
`position`	number	-	Position number (automatically assigned if not provided)
`description`	string		Line item description
`articleNumber`	string	-	Article number
`quantity`	number		Quantity
`unit`	string	-	Unit (UN/ECE Rec 20). Default: C62 (piece)
`unitPrice`	number		Unit price net
`taxRate`	number		VAT rate in percent (e.g. 19, 7, 0)
`taxCategoryCode`	string	-	Tax category code (e.g. "S" for standard, "Z" for 0%, "E" for exempt)
`netAmount`	number	-	Net amount (calculated if not provided)
`taxAmount`	number	-	Tax amount (calculated if not provided)
`grossAmount`	number	-	Gross amount (calculated if not provided)

paymentTerms (Payment Terms)

Parameter	Type	Required	Description
`dueDate`	string	-	Due date in YYYY-MM-DD format
`paymentTermsText`	string	-	Free text for payment terms

Supported Countries and Formats

Use these combinations of countryCode and format in the endpoint path.

DEGermany

PDFZUGFERD 2.3XRECHNUNG 3.0 *

ATAustria

PDFEBINTERFACE *

CHSwitzerland

PDFQR-BILL *

FRFrance

PDFFACTUR-X *

ITItaly

PDFFATTURAPA *

ESSpain

PDFFACTURAE *

NLNetherlands

PDFUBL *

BEBelgium

PDFUBL *

PTPortugalQ2.2026

PDF *

PLPolandQ2.2026

PDF *

CZCzech RepublicQ2.2026

PDFISDOC *

HUHungaryQ2.2026

PDFNAV *

RORomaniaQ2.2026

PDF *

BGBulgariaQ2.2026

PDF *

* Recommended format for the country | = Available | Q2.2026 = Planned

Leitweg-ID for Public Authorities (Germany)

For XRechnung invoices to public authorities (agencies, municipalities, etc.), the Leitweg-ID is mandatory. The format is: XXX-XXXXX-XX

You receive the Leitweg-ID from the contracting authority. A list of all Leitweg-IDs can be found in the official directory.

Error Codes

HTTP	Code	Description	Solution
400	`INVALID_REQUEST`	Invalid request data	Check JSON format and required fields
400	`VALIDATION_FAILED`	E-invoice does not match the schema	Check error messages in errors array
400	`UNSUPPORTED_FORMAT`	Format not supported for this country	Check supported formats for the selected country
401	`UNAUTHORIZED`	Missing or invalid API key	Check the Authorization header (sk_test_* or sk_live_*)
402	`QUOTA_EXCEEDED`	Quota exhausted	Upgrade your plan or wait until next month
422	`INVALID_VAT_ID`	Invalid VAT ID	Check the format (e.g. DE + 9 digits)
422	`INVALID_COUNTRY`	Invalid country code	Use a supported ISO 3166-1 alpha-2 code
429	`RATE_LIMITED`	Too many requests	Wait and try again later

Full error list: Error Handling Documentation

Further Documentation

Validator API

Validate invoices

Converter API

Convert formats

Webhooks

Receive events

Playground

Test API interactively