Core API

Invoice Creator API

Erstelle E-Rechnungen in verschiedenen Formaten für 14 europäische Länder. Unterstützt XRechnung, ZUGFeRD, Factur-X, FatturaPA und viele mehr.

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

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

Authentifizierung

Die API verwendet Bearer Token Authentifizierung. Füge deinen API Key im Authorization Header hinzu:

bash

1Authorization: Bearer sk_live_abc123...

sk_test_* - Test-Modus (keine echten Rechnungen, unbegrenzte Requests)

sk_live_* - Live-Modus (produktive Rechnungen, wird abgerechnet)

Beispiel

bash

1curl -X POST https://api.invoice.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

Bei Erfolg erhältst du 200 OK mit dem erstellten Invoice-Objekt:

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-Felder

Feld	Typ	Beschreibung
`success`	boolean	Gibt an, ob die Rechnung erfolgreich erstellt wurde
`format`	string	Das generierte Format (z.B. XRECHNUNG, ZUGFERD)
`filename`	string	Vorgeschlagener Dateiname für die Rechnung
`mimeType`	string	MIME-Type der generierten Datei (z.B. application/xml, application/pdf)
`hash`	string	SHA-256 Hash des generierten Dokuments
`data`	string	Base64-kodierte Rechnungsdaten
`errors`	array	Liste von Fehlern (code, message, field)
`warnings`	array	Liste von Warnungen (code, message, field)

Request Parameter

Path-Parameter

Parameter	Typ	Beschreibung
`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 (abhängig vom Land): `PDF`, `XRECHNUNG`, `ZUGFERD`, `FACTURX`, `FATTURAPA`, `FACTURAE`, `UBL`, `EBINTERFACE`, `QRBILL`, ISDOC, NAV

XRechnung (Deutschland)

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

ZUGFeRD (Deutschland)

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

Factur-X (Frankreich)

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

FatturaPA (Italien)

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

ebInterface (Österreich)

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

PDF (alle Länder)

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

Body-Parameter

Parameter	Typ	Pflicht	Beschreibung
`invoiceNumber`	string		Eindeutige Rechnungsnummer des Ausstellers
`type`	string	-	Art des Dokuments: "invoice" \| "credit_note" \| "proforma" \| "correction". Standard: "invoice"
`issueDate`	string		Rechnungsdatum im Format YYYY-MM-DD
`dueDate`	string	-	Fälligkeitsdatum im Format YYYY-MM-DD
`deliveryDate`	string	-	Lieferdatum bzw. Leistungsdatum im Format YYYY-MM-DD
`seller`	object		Verkäufer/Rechnungsaussteller (Details siehe unten)
`buyer`	object		Käufer/Rechnungsempfänger (Details siehe unten)
`items`	array		Rechnungspositionen (mindestens 1)
`currency`	string	-	Währungscode (ISO 4217). Standard: EUR
`subtotal`	number	-	Nettosumme (wird automatisch berechnet falls nicht angegeben)
`total`	number	-	Bruttosumme (wird automatisch berechnet falls nicht angegeben)
`taxSummary`	array	-	Steuerübersicht nach Steuersätzen (wird automatisch berechnet)
`paymentTerms`	object	-	Zahlungsbedingungen (dueDate, paymentTermsText)
`notes`	string	-	Freitext-Bemerkung auf der Rechnung

seller (Verkäufer)

Parameter	Typ	Pflicht	Beschreibung
`name`	string		Firmenname
`street`	string		Straße und Hausnummer
`city`	string		Stadt
`postalCode`	string		Postleitzahl
`country`	string		Ländercode (ISO 3166-1 alpha-2)
`taxId`	string	-	Steuernummer
`vatId`	string	-	USt-IdNr. (z.B. DE123456789)
`email`	string	-	E-Mail-Adresse
`phone`	string	-	Telefonnummer

buyer (Käufer)

Parameter	Typ	Pflicht	Beschreibung
`name`	string		Firmenname
`street`	string		Straße und Hausnummer
`city`	string		Stadt
`postalCode`	string		Postleitzahl
`country`	string		Ländercode (ISO 3166-1 alpha-2)
`taxId`	string	-	Steuernummer des Käufers
`vatId`	string	-	USt-IdNr. des Käufers
`email`	string	-	E-Mail-Adresse
`phone`	string	-	Telefonnummer

items[] (Positionen)

Parameter	Typ	Pflicht	Beschreibung
`position`	number	-	Positionsnummer (wird automatisch vergeben falls nicht angegeben)
`description`	string		Beschreibung der Position
`articleNumber`	string	-	Artikelnummer
`quantity`	number		Menge
`unit`	string	-	Einheit (UN/ECE Rec 20). Standard: C62 (Stück)
`unitPrice`	number		Einzelpreis netto
`taxRate`	number		Mehrwertsteuersatz in Prozent (z.B. 19, 7, 0)
`taxCategoryCode`	string	-	Steuerkategorie-Code (z.B. "S" für Standard, "Z" für 0%, "E" für befreit)
`netAmount`	number	-	Nettobetrag (wird berechnet falls nicht angegeben)
`taxAmount`	number	-	Steuerbetrag (wird berechnet falls nicht angegeben)
`grossAmount`	number	-	Bruttobetrag (wird berechnet falls nicht angegeben)

paymentTerms (Zahlungsbedingungen)

Parameter	Typ	Pflicht	Beschreibung
`dueDate`	string	-	Fälligkeitsdatum im Format YYYY-MM-DD
`paymentTermsText`	string	-	Freitext für Zahlungsbedingungen

Unterstützte Länder und Formate

Verwende diese Kombinationen aus countryCode und format im Endpoint-Pfad.

DEDeutschland

PDFZUGFERD 2.3XRECHNUNG 3.0 *

ATÖsterreich

PDFEBINTERFACE *

CHSchweiz

PDFQR-BILL *

FRFrankreich

PDFFACTUR-X *

ITItalien

PDFFATTURAPA *

ESSpanien

PDFFACTURAE *

NLNiederlande

PDFUBL *

BEBelgien

PDFUBL *

PTPortugalQ2.2026

PDF *

PLPolenQ2.2026

PDF *

CZTschechienQ2.2026

PDFISDOC *

HUUngarnQ2.2026

PDFNAV *

RORumänienQ2.2026

PDF *

BGBulgarienQ2.2026

PDF *

* Empfohlenes Format für das Land | = Verfügbar | Q2.2026 = Geplant

Leitweg-ID für öffentliche Auftraggeber (Deutschland)

Bei XRechnung an öffentliche Auftraggeber (Behörden, Kommunen, etc.) ist die Leitweg-ID Pflicht. Das Format ist: XXX-XXXXX-XX

Die Leitweg-ID erhältst du vom Auftraggeber. Eine Liste aller Leitweg-IDs findest du im offiziellen Verzeichnis.

Fehler-Codes

HTTP	Code	Beschreibung	Lösung
400	`INVALID_REQUEST`	Ungültige Request-Daten	Überprüfe das JSON-Format und Pflichtfelder
400	`VALIDATION_FAILED`	E-Rechnung entspricht nicht dem Schema	Prüfe die Fehlermeldungen im errors-Array
400	`UNSUPPORTED_FORMAT`	Format für dieses Land nicht unterstützt	Prüfe die unterstützten Formate für das gewählte Land
401	`UNAUTHORIZED`	Fehlender oder ungültiger API Key	Prüfe den Authorization Header (sk_test_* oder sk_live_*)
402	`QUOTA_EXCEEDED`	Kontingent aufgebraucht	Upgrade deinen Plan oder warte bis zum nächsten Monat
422	`INVALID_VAT_ID`	Ungültige USt-IdNr.	Überprüfe das Format (z.B. DE + 9 Ziffern)
422	`INVALID_COUNTRY`	Ungültiger Ländercode	Verwende einen unterstützten ISO 3166-1 alpha-2 Code
429	`RATE_LIMITED`	Zu viele Anfragen	Warte und versuche es später erneut

Vollständige Fehlerliste: Error Handling Dokumentation

Weiterführende Dokumentation

Validator API

Rechnungen validieren

Converter API

Formate konvertieren

Webhooks

Events empfangen

Playground

API interaktiv testen