Reference

OpenAPI Specification

Our complete API is available as an OpenAPI 3.1 specification — for looking up every endpoint and for interactive documentation. It is not yet suitable for code generation; the note further down names the four defects.

Download

OpenAPI specification (JSON)

Full spec, all 81 endpoints — public, no login. Fine for reading; not yet suitable for code generation (see the note below).

openapi-full.json

Interactive reference

Browse and try every endpoint in the browser

service.invoice-api.xhub.io/docs-full

API Endpoints

The most important endpoints of the Invoice-api.xhub API (Version 1.4.0):

POST/api/v1/invoice/{countryCode}/{format}/generate
E-Invoice GenerationAuth
POST/api/v1/invoice/parse
E-Invoice ParsingAuth
POST/api/v1/invoice/{countryCode}/validate
ValidationAuth
GET/api/v1/invoice/{countryCode}/formats
Formats per countryAuth
GET/api/v1/invoice/formats
All available formatsAuth
POST/api/v1/invoice/convert
Format conversionAuth
POST/api/v1/invoice/attachments
Embed files into an invoice PDFAuth
POST/api/v1/pdf/attachments
Embed files into any PDFAuth
POST/api/v1/invoice/es/verifactu-qr
VeriFactu QR code (ES)Auth

Authentication

Bearer Token

Authenticate with your API key in the Authorization header:

bash
1Authorization: Bearer sk_live_xxxxxxxxxxxxx
2 
3# Testmodus
4Authorization: Bearer sk_test_xxxxxxxxxxxxx

Live Keys (sk_live_*) are for production data. Test Keys (sk_test_*) are for development and testing.

Supported Countries

The API supports e-invoice formats for the following countries:

DE

Germany

AT

Austria

CH

Switzerland

FR

France

IT

Italy

ES

Spain

NL

Netherlands

BE

Belgium

PL

Poland

PT

Portugal

AE

United Arab Emirates

AU

Australia

BG

Bulgaria

CY

Cyprus

CZ

Czech Republic

DK

Denmark

EE

Estonia

FI

Finland

GB

United Kingdom

GR

Greece

HR

Croatia

HU

Hungary

IE

Ireland

IS

Iceland

JP

Japan

LI

Liechtenstein

LT

Lithuania

LU

Luxembourg

LV

Latvia

MT

Malta

NO

Norway

NZ

New Zealand

OM

Oman

RO

Romania

SE

Sweden

SI

Slovenia

SK

Slovakia

Preview

Excerpt from the OpenAPI specification: service.invoice-api.xhub.io/openapi-full.json

yaml
1openapi: 3.1.0
2info:
3  title: Invoice.xhub API
4  version: 1.4.0
5 
6servers:
7  # Relative — the spec is served from the API host itself, so an import
8  # without a base URL has no host to call. Set it in your client:
9  # https://service.invoice-api.xhub.io
10  - url: /
11    description: Invoice API v1
12 
13security:
14  - bearerAuth: []
15 
16paths:
17  /api/v1/invoice/{countryCode}/{format}/generate:
18    post:
19      summary: Generate invoice document
20      parameters:
21        - name: countryCode
22          in: path
23          required: true
24          schema:
25            type: string
26            # 37 Länder, klein geschrieben — Auszug:
27            enum: [ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, ...]
28        - name: format
29          in: path
30          required: true
31          schema:
32            type: string
33            # 15 Format-Slots — Auszug:
34            enum: [pdf, xrechnung, zugferd, facturx, ubl, ...]
35      # ...
36 
37  /api/v1/invoice/{countryCode}/validate:
38    post:
39      summary: Validate invoice data
40      description: >-
41        Validate invoice data against country-specific rules and e-invoice
42        format requirements. Returns validation errors and warnings without
43        consuming billing quota. Braucht wie jeder Endpoint einen API-Key und
44        ist an das Kontingent gebunden (aufgebraucht = 429).
45      # ...
46 
47  /api/v1/invoice/convert:
48    post:
49      summary: Convert an e-invoice between formats
50      # ...
51 
52components:
53  securitySchemes:
54    bearerAuth:
55      type: http
56      scheme: bearer
57      bearerFormat: API Key
58      description: >-
59        API Key authentication. Use `sk_live_*` for production or `sk_test_*`
60        for testing.
61  # ...

Import into API Clients

Read before importing: the spec is not generator-ready yet

The file imports, but four measured defects (as of 2026-09-15) leave clients and generated code without any models:

  • • 138 of 138 internal `$ref`s point at `#/components/schemas/__schema0` — a schema the file does not define. Request and response models therefore come out empty.
  • • 65 request bodies appear as `{"vendor":"zod"}` instead of a JSON schema.
  • • `POST /api/v1/invoice/convert` carries no `requestBody` at all.
  • • `servers` is `[{"url":"/"}]` — relative. Add `https://service.invoice-api.xhub.io` as the base URL in your client, or every call goes nowhere.

Until that is fixed: the complete invoice field structure, generated from the same spec, is on /docs/api/schema , and the examples on the reference pages are verified against the spec (`pnpm exec node scripts/verify-doc-examples.mjs`).

Postman

bash
1# Via URL importieren
21. Öffne Postman
32. Klicke auf "Import" (oben links)
43. Wähle "Link" Tab
54. Füge ein: https://service.invoice-api.xhub.io/openapi-full.json
65. Klicke "Continue" → "Import" (Postman liest OpenAPI 3 direkt)
7 
8# Alternativ: Spec herunterladen und als Datei importieren
9curl -O https://service.invoice-api.xhub.io/openapi-full.json

Insomnia

bash
1# Via URL importieren
21. Öffne Insomnia
32. Application → Preferences → Data
43. "Import Data" → "From URL"
54. URL: https://service.invoice-api.xhub.io/openapi-full.json
65. "Fetch and Import"

Code Generation

Generate type-safe API clients from the OpenAPI specification:

Note: because of the dangling `$ref`s described above, these generators currently produce clients with empty models. The commands are listed so they are correct the moment the backend fix lands.

bash
1# TypeScript/JavaScript mit openapi-typescript
2npx openapi-typescript https://service.invoice-api.xhub.io/openapi-full.json -o ./types/api.d.ts
3 
4# Python mit openapi-python-client
5pip install openapi-python-client
6openapi-python-client generate --url https://service.invoice-api.xhub.io/openapi-full.json
7 
8# Go mit oapi-codegen
9go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
10oapi-codegen -package api https://service.invoice-api.xhub.io/openapi-full.json > api/api.gen.go

Recommended Tools

Postman

Popular API client with collection support

Insomnia

Open-source REST client

Redoc

Beautiful API documentation from OpenAPI

Versioning

The OpenAPI specification is updated with API changes. Use the version number in the spec to ensure compatibility. Breaking changes are announced in the Changelog.

Further Documentation

Quickstart

Getting started

Authentication

Set up API keys

Creator API

Create invoices

Playground

Test API interactively