Core API

Invoice Creator API

Erstelle XRechnung und ZUGFeRD-Rechnungen aus strukturierten JSON-Daten. Validierung und PDF-Generierung inklusive.

POST/v1/invoices

Beispiel

bash

1curl -X POST https://api.xhub.io/v1/invoices \
2  -H "Authorization: Bearer xhub_live_abc123..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "format": "xrechnung-3.0",
6    "invoiceNumber": "RE-2025-001",
7    "issueDate": "2025-01-15",
8    "dueDate": "2025-02-15",
9    "seller": {
10      "name": "Meine Firma GmbH",
11      "vatId": "DE123456789",
12      "email": "rechnung@meinefirma.de",
13      "address": {
14        "street": "Musterstraße 1",
15        "city": "Berlin",
16        "zip": "10115",
17        "country": "DE"
18      }
19    },
20    "buyer": {
21      "name": "Kunde AG",
22      "vatId": "DE987654321",
23      "leitweg": "991-12345-67",
24      "email": "einkauf@kunde.de",
25      "address": {
26        "street": "Kundenweg 42",
27        "city": "München",
28        "zip": "80331",
29        "country": "DE"
30      }
31    },
32    "items": [
33      {
34        "description": "Beratungsleistung",
35        "quantity": 10,
36        "unit": "HUR",
37        "unitPrice": 150.00,
38        "vat": 19
39      }
40    ],
41    "paymentTerms": {
42      "iban": "DE89370400440532013000",
43      "bic": "COBADEFFXXX",
44      "reference": "RE-2025-001"
45    }
46  }'

Response

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

json

1{
2  "id": "inv_abc123xyz",
3  "status": "valid",
4  "format": "XRechnung 3.0.2",
5  "created": "2025-01-15T10:30:00Z",
6  "invoiceNumber": "RE-2025-001",
7  "validation": {
8    "valid": true,
9    "errors": [],
10    "warnings": []
11  },
12  "totals": {
13    "net": 1500.00,
14    "vat": 285.00,
15    "gross": 1785.00,
16    "currency": "EUR"
17  },
18  "download": {
19    "xml": "https://api.xhub.io/v1/invoices/inv_abc123xyz/xml",
20    "pdf": "https://api.xhub.io/v1/invoices/inv_abc123xyz/pdf"
21  }
22}

Request Parameter

Haupt-Parameter

Parameter	Typ	Pflicht	Beschreibung
`format`	string		Zielformat der Rechnung. Unterstützte Werte: xrechnung-3.0, xrechnung-2.3, zugferd-2.1, zugferd-2.0, factur-x-1.0
`invoiceNumber`	string		Eindeutige Rechnungsnummer des Ausstellers
`issueDate`	string		Rechnungsdatum im Format YYYY-MM-DD
`dueDate`	string	-	Fälligkeitsdatum 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)
`paymentTerms`	object	-	Zahlungsinformationen (IBAN, BIC, Referenz)
`note`	string	-	Freitext-Bemerkung auf der Rechnung
`currency`	string	-	Währungscode (ISO 4217). Standard: EUR

seller (Verkäufer)

Parameter	Typ	Pflicht	Beschreibung
`name`	string		Firmenname
`vatId`	string		USt-IdNr. (z.B. DE123456789)
`taxNumber`	string	-	Steuernummer (alternativ zu vatId)
`email`	string	-	E-Mail
`phone`	string	-	Telefon
`address`	object		Adresse (street, city, zip, country)
`bankAccount`	object	-	Bankverbindung (iban, bic, bankName)

buyer (Käufer)

Parameter	Typ	Pflicht	Beschreibung
`name`	string		Firmenname
`vatId`	string	-	USt-IdNr. des Käufers
`leitweg`	string	-	Leitweg-ID für öffentliche Auftraggeber (XRechnung)
`email`	string	-	E-Mail
`address`	object		Adresse (street, city, zip, country)
`reference`	string	-	Bestellnummer/Referenz des Käufers

items[] (Positionen)

Parameter	Typ	Pflicht	Beschreibung
`description`	string		Beschreibung der Position
`quantity`	number		Menge
`unit`	string	-	Einheit (UN/ECE Rec 20). Standard: C62 (Stück)
`unitPrice`	number		Einzelpreis netto
`vat`	number		Mehrwertsteuersatz in Prozent (z.B. 19, 7, 0)
`articleNumber`	string	-	Artikelnummer
`discount`	number	-	Rabatt in Prozent

Unterstützte Formate

xrechnung-3.0Empfohlen

XRechnung 3.0.2

Aktueller deutscher Standard für B2G

xrechnung-2.3

XRechnung 2.3

Ältere Version (bis Ende 2024 gültig)

zugferd-2.1Empfohlen

ZUGFeRD 2.1.1

Hybrid-Format mit eingebettetem PDF

zugferd-2.0

ZUGFeRD 2.0

Ältere ZUGFeRD-Version

factur-x-1.0

Factur-X 1.0

Französischer Standard (kompatibel mit ZUGFeRD)

Leitweg-ID für öffentliche Auftraggeber

Bei Rechnungen 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`	Rechnung entspricht nicht dem Schema	Prüfe die Fehlermeldungen im validation-Objekt
401	`UNAUTHORIZED`	Fehlender oder ungültiger API Key	Prüfe den Authorization Header
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_LEITWEG`	Ungültige Leitweg-ID	Format: XXX-XXXXX-XX (z.B. 991-12345-67)
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