Core API

Invoice Creator API

Erstelle E-Rechnungen in verschiedenen Formaten für 37 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 für die Entwicklung — gleiche Antwort, gleiches Kontingent und gleiches Rate-Limit wie ein Live-Key

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

Beispiel

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      "bankAccount": {
22        "iban": "DE89370400440532013000",
23        "bic": "COBADEFFXXX"
24      }
25    },
26    "buyer": {
27      "name": "Kunde AG",
28      "street": "Kundenweg 42",
29      "city": "München",
30      "postalCode": "80331",
31      "countryCode": "DE",
32      "vatId": "DE987654321",
33      "email": "einkauf@kunde.de"
34    },
35    "countrySpecific": {
36      "countryCode": "DE",
37      "buyerReference": "BUYER-REF-001"
38    },
39    "items": [
40      {
41        "position": 1,
42        "description": "Beratungsleistung",
43        "articleNumber": "CONS-001",
44        "quantity": 10,
45        "unit": "HUR",
46        "unitPrice": 150.00,
47        "taxRate": 19,
48        "taxCategoryCode": "S",
49        "netAmount": 1500.00,
50        "taxAmount": 285.00,
51        "grossAmount": 1785.00
52      }
53    ],
54    "subtotal": 1500.00,
55    "total": 1785.00,
56    "taxSummary": [
57      {
58        "taxRate": 19,
59        "netAmount": 1500.00,
60        "taxAmount": 285.00
61      }
62    ],
63    "paymentTerms": {
64      "dueDays": 30,
65      "description": "Zahlbar innerhalb von 30 Tagen ohne Abzug"
66    },
67    "paymentMethods": [
68      {
69        "type": "bank_transfer",
70        "details": "SEPA-Überweisung"
71      }
72    ],
73    "notes": "Vielen Dank für Ihren Auftrag!"
74    }
75  }'

Response

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

json

1{
2  "success": true,
3  "format": "xrechnung",
4  "filename": "RE-2026-0042.xml",
5  "mimeType": "application/xml",
6  "hash": "9f2c1b7d4e8a03f5c6b9d0e1a2f3c4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
7  "payloadHash": "3b1e6c5a9d2f04b7e8c1a0f3d6b9e2c5a8f1d4b7e0c3a6f9d2b5e8c1a4f7d0b3",
8  "data": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...base64encoded...",
9  "errors": [],
10  "complianceErrors": [],
11  "warnings": [
12    {
13      "code": "MISSING_OPTIONAL",
14      "message": "Buyer reference is recommended for public-sector invoices",
15      "field": "countrySpecific.buyerReference"
16    }
17  ]
18}

Response-Felder

Feld	Typ	Beschreibung
`success`	boolean	Gibt an, ob die Rechnung erfolgreich erstellt wurde
`format`	string	Das generierte Format, durchgehend klein geschrieben (z. B. xrechnung, zugferd, facturx, pdf)
`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, klein geschrieben — alle 37: `ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk`
`format`required	string	Zielformat — alle 15: `ebinterface, facturae, facturx, fatturapa, hr-fisk, isdoc, ksef, mydata, nav, pdf, peppol-ubl, qr-bill, ubl, xrechnung, zugferd`

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 \| correction \| proforma \| partial \| partial_construction \| partial_final_construction \| final_construction \| self_billed. Standard: invoice. proforma wird bei XRechnung und Peppol BIS mit 422 abgewiesen.
`issueDate`	string		Rechnungsdatum im Format YYYY-MM-DD
`dueDate`	string	-	Fälligkeitsdatum im Format YYYY-MM-DD — optional, die Spec führt dueDate nicht in invoice.required
`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)
`orderNumber`	string	-	Bestellnummer (Purchase Order Reference)
`customerNumber`	string	-	Kundennummer beim Verkäufer
`contractNumber`	string	-	Vertragsnummer
`servicePeriod`	object	-	Leistungszeitraum (start, end als ISO 8601 Datum)
`paymentTerms`	object	-	Zahlungsbedingungen (dueDays, description, earlyPaymentDiscount mit days und discountPercent)
`paymentMethods`	array	-	Zahlungsmethoden (type: bank_transfer\|direct_debit\|credit_card …, details als Freitext) — bei bank_transfer muss seller.bankAccount mit IBAN gesetzt sein
`countrySpecific`	object	-	Länderspezifische Felder — countryCode ist Pflicht (z. B. "DE"). Für DE zusätzlich: buyerReference (BT-10), paymentMeansCode (BT-81), leitwegId (B2G), isKleinunternehmer
`notes`	string	-	Freitext-Bemerkung auf der Rechnung
`templateId`	string	-	Referenz auf gespeichertes PDF-Template per UUID
`formatOptions.template`	string	-	Inline BlockTemplate JSON für PDF-Layout
`formatOptions.zugferdProfile`	string	-	ZUGFeRD-/Factur-X-Profil: EN16931, BASIC oder EXTENDED. Bei /generate heißt der Schlüssel formatOptions.profile; zugferdProfile ist nur noch ein veralteter Alias. MINIMUM und BASIC WL werden mit 400 abgewiesen.

seller (Verkäufer)

Parameter	Typ	Pflicht	Beschreibung
`name`	string		Firmenname
`tradingName`	string	-	Handelsname (wenn abweichend vom juristischen Namen)
`street`	string		Straße und Hausnummer
`additionalStreet`	string	-	Zusätzliche Adresszeile
`city`	string		Stadt
`postalCode`	string		Postleitzahl
`state`	string	-	Bundesland/Region (ISO 3166-2)
`countryCode`	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
`website`	string	-	Website-URL
`bankAccount`	object	-	Bankverbindung (iban, bic, bankName, accountHolder) — Pflicht, sobald paymentMethods eine Überweisung enthält (EN 16931, BR-61)

buyer (Käufer)

Parameter	Typ	Pflicht	Beschreibung
`name`	string		Firmenname
`tradingName`	string	-	Handelsname (wenn abweichend vom juristischen Namen)
`street`	string		Straße und Hausnummer
`additionalStreet`	string	-	Zusätzliche Adresszeile
`city`	string		Stadt
`postalCode`	string		Postleitzahl
`state`	string	-	Bundesland/Region (ISO 3166-2)
`countryCode`	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
`website`	string	-	Website-URL
`bankAccount`	object	-	Bankverbindung (iban, bic, bankName, accountHolder) — Pflicht, sobald paymentMethods eine Überweisung enthält (EN 16931, BR-61)

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
`dueDays`	number	-	Zahlungsziel in Tagen (Pflicht)
`description`	string	-	Freitext-Beschreibung der Zahlungsbedingungen
`earlyPaymentDiscount`	object	-	Skonto: { days, discountPercent }

37 unterstützte Länder und ihre Formate

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

DEDeutschland

PDFZUGFeRD 2.3/2.4/2.5XRechnung 3.0/3.0.2 *

ATÖsterreich

PDFebInterface *UBL (Peppol BIS 3.0)

CHSchweiz

PDFZUGFeRD (CH)QR-Bill *

FRFrankreich

PDFFactur-X 1.0/1.08/1.09 *UBL (Peppol BIS 3.0)

ITItalien

PDFFatturaPA 1.2.3 *

ESSpanien

PDFFacturae *UBL (Peppol BIS 3.0)

NLNiederlande

PDFUBL (Peppol BIS 3.0 / NL-CIUS)

BEBelgien

PDFUBL (Peppol BIS 3.0)Factur-X

PLPolen

PDFKSeF FA(3) (national UBL slot) *UBL (Peppol BIS 3.0)

PTPortugal

PDFCIUS-PT (national UBL) *UBL (Peppol BIS 3.0)

AEVereinigte Arabische Emirate

PDFUBL (PINT-AE)

AUAustralien

PDFUBL (PINT AU-NZ)

BGBulgarien

PDFUBL (Peppol BIS 3.0)

CYZypern

PDFUBL (Peppol BIS 3.0)

CZTschechien

PDFISDOC *UBL (Peppol BIS 3.0)

DKDänemark

PDFUBL (Peppol BIS 3.0)

EEEstland

PDFUBL (Peppol BIS 3.0)

FIFinnland

PDFUBL (Peppol BIS 3.0)

GBGroßbritannien

PDFUBL (Peppol BIS 3.0 / UK)

GRGriechenland

PDFmyDATA *

HRKroatien

PDFUBL (Peppol BIS 3.0)

HUUngarn

PDFNAV *

IEIrland

PDFUBL (Peppol BIS 3.0)

ISIsland

PDFUBL (Peppol BIS 3.0)

JPJapan

PDFUBL (PINT-JP)

LILiechtenstein

PDFQR-BillUBL (Peppol BIS 3.0)

LTLitauen

PDFUBL (Peppol BIS 3.0)

LULuxemburg

PDFUBL (Peppol BIS 3.0)

LVLettland

PDFUBL (Peppol BIS 3.0)

MTMalta

PDFUBL (Peppol BIS 3.0)

NONorwegen

PDFUBL (Peppol BIS 3.0)

NZNeuseeland

PDFUBL (PINT AU-NZ)

OMOman

PDFUBL (PINT-OM)

RORumänien

PDFeFactura (CIUS-RO) *UBL (Peppol BIS 3.0)

SESchweden

PDFUBL (Peppol BIS 3.0)

SISlowenien

PDFUBL (Peppol BIS 3.0)

SKSlowakei

PDFUBL (Peppol BIS 3.0)

* Empfohlenes Format für das Land | = Verfügbar

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.

Grenzen

Die Zahl der Rechnungspositionen in items[] ist je Tarif begrenzt. Die Grenze gilt beim Erzeugen, bei beiden Prüf-Routen und beim Umwandeln — nicht beim Auslesen.

Tarif	Positionen je Rechnung
Free	25
Starter	100
Premium	1.000
Enterprise	individuell vereinbart

Mehr als 15.000 Positionen je Rechnung lehnt die API in jedem Fall ab. Das ist die technische Obergrenze des Dienstes, die nur der Enterprise-Vertrag ausschöpft.

Antwort bei Überschreitung

Wird die Grenze überschritten, antwortet die API mit HTTP 400 und dem Fehlercode TOO_MANY_LINE_ITEMS. Die Antwort nennt gezählte Anzahl und Limit; es wird keine Rechnung erzeugt und der Call nicht abgerechnet.

json

1{
2  "error": "TOO_MANY_LINE_ITEMS",
3  "message": "Too many line items for this plan",
4  "lineItems": {
5    "count": 128,
6    "limit": 100
7  }
8}

Welcher Tarif welche Grenze hat: Preise und Positionen je Tarif

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
400	`TOO_MANY_LINE_ITEMS`	Die Rechnung hat mehr Positionen, als der Tarif erlaubt	lineItems.count und lineItems.limit lesen, Beleg aufteilen oder Tarif wechseln — siehe Grenzen
401	`UNAUTHORIZED`	Fehlender oder ungültiger API Key	Prüfe den Authorization Header (sk_test_* oder sk_live_*)
403	`FORBIDDEN`	Missing required entitlement	Prüfe den Authorization Header (sk_test_* oder sk_live_*)
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	`QUOTA_EXCEEDED`	Kontingent aufgebraucht	Upgrade deinen Plan oder warte bis zum nächsten Monat
500	`INTERNAL_ERROR`	Internal Server Error	Retry the request or contact support

Vollständige Fehlerliste: Error Handling Dokumentation

Weiterführende Dokumentation

Feldreferenz

Alle Felder des invoice-Objekts mit Typ und Pflichtangabe

Validator API

Rechnungen validieren

Converter API

Formate konvertieren

Webhooks

Events empfangen

Playground

API interaktiv testen