Reference

OpenAPI Specification

Unsere vollständige API ist als OpenAPI 3.1 Spezifikation verfügbar — zum Nachlesen jedes Endpunkts und für interaktive Dokumentation. Für Code-Generierung ist sie noch nicht geeignet; der Hinweis weiter unten nennt die vier Mängel.

Download

OpenAPI-Spezifikation (JSON)

Vollständige Spec, alle 81 Endpunkte — öffentlich, ohne Login. Zum Lesen geeignet; zur Code-Generierung noch nicht (siehe Hinweis unten).

openapi-full.json

Interaktive Referenz

Alle Endpunkte im Browser durchsuchen und ausprobieren

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

API Endpoints

Die wichtigsten Endpoints der Invoice-api.xhub API (Version 1.4.0):

POST/api/v1/invoice/{countryCode}/{format}/generate
E-Invoice GenerierungAuth
POST/api/v1/invoice/parse
E-Invoice ParsingAuth
POST/api/v1/invoice/{countryCode}/validate
ValidierungAuth
GET/api/v1/invoice/{countryCode}/formats
Formate pro LandAuth
GET/api/v1/invoice/formats
Alle verfügbaren FormateAuth
POST/api/v1/invoice/convert
FormatumwandlungAuth
POST/api/v1/invoice/attachments
Dateien in ein Rechnungs-PDF einbettenAuth
POST/api/v1/pdf/attachments
Dateien in ein beliebiges PDF einbettenAuth
POST/api/v1/invoice/es/verifactu-qr
VeriFactu-QR-Code (ES)Auth

Authentifizierung

Bearer Token

Authentifiziere dich mit deinem API Key im Authorization Header:

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

Live Keys (sk_live_*) sind für Produktionsdaten. Test Keys (sk_test_*) sind für Entwicklung und Tests.

Unterstützte Länder

Die API unterstützt E-Rechnungsformate für folgende Länder:

DE

Deutschland

AT

Österreich

CH

Schweiz

FR

Frankreich

IT

Italien

ES

Spanien

NL

Niederlande

BE

Belgien

PL

Polen

PT

Portugal

AE

Vereinigte Arabische Emirate

AU

Australien

BG

Bulgarien

CY

Zypern

CZ

Tschechien

DK

Dänemark

EE

Estland

FI

Finnland

GB

Großbritannien

GR

Griechenland

HR

Kroatien

HU

Ungarn

IE

Irland

IS

Island

JP

Japan

LI

Liechtenstein

LT

Litauen

LU

Luxemburg

LV

Lettland

MT

Malta

NO

Norwegen

NZ

Neuseeland

OM

Oman

RO

Rumänien

SE

Schweden

SI

Slowenien

SK

Slowakei

Vorschau

Auszug aus der OpenAPI Spezifikation: 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 in API-Clients

Vor dem Import lesen: die Spec ist noch nicht generator-tauglich

Die Datei lässt sich importieren, aber vier gemessene Mängel (Stand 2026-09-15) sorgen dafür, dass Clients und generierter Code ohne Modelle ankommen:

  • • 138 von 138 internen `$ref` zeigen auf `#/components/schemas/__schema0` — ein Schema, das die Datei nicht definiert. Request- und Response-Modelle bleiben dadurch leer.
  • • 65 Request-Bodies stehen als `{"vendor":"zod"}` in der Datei statt als JSON-Schema.
  • • `POST /api/v1/invoice/convert` trägt überhaupt keinen `requestBody`.
  • • `servers` ist `[{"url":"/"}]` — relativ. Im Client muss `https://service.invoice-api.xhub.io` als Base URL nachgetragen werden, sonst geht jeder Aufruf ins Leere.

Bis das behoben ist: Die Feldstruktur der Rechnung steht vollständig und aus derselben Spec erzeugt auf /docs/api/schema , und die Beispiele auf den Referenzseiten sind gegen die Spec geprüft (`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-Generierung

Generiere typsichere API-Clients aus der OpenAPI Spezifikation:

Achtung: Wegen der oben genannten hängenden `$ref` erzeugen diese Generatoren heute Clients mit leeren Modellen. Die Befehle stehen hier, damit sie nach dem Backend-Fix sofort stimmen.

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

Empfohlene Tools

Postman

Beliebter API-Client mit Collection-Support

Insomnia

Open-Source REST-Client

Redoc

Schöne API-Dokumentation aus OpenAPI

Versionierung

Die OpenAPI Spezifikation wird bei API-Änderungen aktualisiert. Nutze die Versionsnummer in der Spec, um Kompatibilität sicherzustellen. Breaking Changes werden im Changelogangekündigt.

Weiterführende Dokumentation

Quickstart

Erste Schritte

Authentication

API Keys einrichten

Creator API

Rechnungen erstellen

Playground

API interaktiv testen