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    "invoice": {
6    "invoiceNumber": "RE-2025-001",
7    "type": "invoice",
8    "issueDate": "2025-01-15",
9    "dueDate": "2025-02-15",
10    "currency": "EUR",
11    "seller": {
12      "name": "Meine Firma GmbH",
13      "street": "Musterstraße 1",
14      "city": "Berlin",
15      "postalCode": "10115",
16      "countryCode": "DE",
17      "taxId": "123/456/78901",
18      "vatId": "DE123456789",
19      "email": "rechnung@meinefirma.de",
20      "phone": "+49 30 1234567"
21    },
22    "buyer": {
23      "name": "Kunde AG",
24      "street": "Kundenweg 42",
25      "city": "München",
26      "postalCode": "80331",
27      "countryCode": "DE",
28      "vatId": "DE987654321",
29      "email": "einkauf@kunde.de"
30    },
31    "countrySpecific": {
32      "buyerReference": "BUYER-REF-001"
33    },
34    "items": [
35      {
36        "position": 1,
37        "description": "Beratungsleistung",
38        "articleNumber": "CONS-001",
39        "quantity": 10,
40        "unit": "HUR",
41        "unitPrice": 150.00,
42        "taxRate": 19,
43        "taxCategoryCode": "S",
44        "netAmount": 1500.00,
45        "taxAmount": 285.00,
46        "grossAmount": 1785.00
47      }
48    ],
49    "paymentTerms": {
50      "dueDays": 30,
51      "description": "Zahlbar innerhalb von 30 Tagen ohne Abzug"
52    },
53    "notes": "Vielen Dank für Ihren Auftrag!"
54    }
55  }'

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)
`orderNumber`	string	-	Purchase order reference number
`customerNumber`	string	-	Customer number at the seller
`contractNumber`	string	-	Contract number
`servicePeriod`	object	-	Service period (start, end as ISO 8601 date)
`paymentTerms`	object		Payment terms (dueDate, paymentTermsText)
`paymentMethods`	array	-	Payment methods (type: bank_transfer\|direct_debit\|credit_card, details)
`countrySpecific`	object	-	Country-specific fields (DE: buyerReference, paymentMeansCode, leitwegId, isKleinunternehmer)
`notes`	string	-	Free-text note on the invoice
`templateId`	string	-	Reference to a saved PDF template by UUID
`formatOptions.template`	string	-	Inline BlockTemplate JSON for PDF layout
`formatOptions.zugferdProfile`	string	-	ZUGFeRD profile (MINIMUM, BASIC, EN16931, EXTENDED)

seller (Seller)

Parameter	Type	Required	Description
`name`	string		Company name
`tradingName`	string	-	Trading name (if different from legal name)
`street`	string		Street and house number
`additionalStreet`	string	-	Additional address line
`city`	string		City
`postalCode`	string		Postal code
`state`	string	-	State/region (ISO 3166-2)
`countryCode`	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
`website`	string	-	Website URL
`bankAccount`	object	-	Bank account (iban, bic, bankName, accountHolder)

buyer (Buyer)

Parameter	Type	Required	Description
`name`	string		Company name
`tradingName`	string	-	Trading name (if different from legal name)
`street`	string		Street and house number
`additionalStreet`	string	-	Additional address line
`city`	string		City
`postalCode`	string		Postal code
`state`	string	-	State/region (ISO 3166-2)
`countryCode`	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
`website`	string	-	Website URL
`bankAccount`	object	-	Bank account (iban, bic, bankName, accountHolder)

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
`dueDays`	number	-	Payment term in days (required)
`description`	string	-	Free-text description of payment terms
`earlyPaymentDiscount`	object	-	Early-payment discount: { days, discountPercent }

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_*)
403	`FORBIDDEN`	Missing required entitlement	Check the Authorization header (sk_test_* or sk_live_*)
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	`QUOTA_EXCEEDED`	Quota exhausted	Upgrade your plan or wait until next month
500	`INTERNAL_ERROR`	Internal Server Error	Retry the request or contact support

Full error list: Error Handling Documentation

Further Documentation

Validator API

Validate invoices

Converter API

Convert formats

Webhooks

Receive events

Playground

Test API interactively