Core API

Invoice Creator API

Erstelle E-Rechnungen in verschiedenen Formaten für 28 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://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    },
22    "buyer": {
23      "name": "Kunde AG",
24      "street": "Kundenweg 42",
25      "city": "München",
26      "postalCode": "80331",
27      "countryCode": "DE",
28      "vatId": "DE987654321",
29      "email": "einkauf@kunde.de"
30    },
31    "countrySpecific": {
32      "buyerReference": "BUYER-REF-001"
33    },
34    "items": [
35      {
36        "position": 1,
37        "description": "Beratungsleistung",
38        "articleNumber": "CONS-001",
39        "quantity": 10,
40        "unit": "HUR",
41        "unitPrice": 150.00,
42        "taxRate": 19,
43        "taxCategoryCode": "S",
44        "netAmount": 1500.00,
45        "taxAmount": 285.00,
46        "grossAmount": 1785.00
47      }
48    ],
49    "paymentTerms": {
50      "dueDays": 30,
51      "description": "Zahlbar innerhalb von 30 Tagen ohne Abzug"
52    },
53    "notes": "Vielen Dank für Ihren Auftrag!"
54    }
55  }'

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: `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)
`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 (dueDate, paymentTermsText)
`paymentMethods`	array	-	Zahlungsmethoden (type: bank_transfer\|direct_debit\|credit_card, details)
`countrySpecific`	object	-	Länderspezifische Felder (DE: buyerReference, paymentMeansCode, leitwegId, 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-Profil (MINIMUM, BASIC, EN16931, EXTENDED)

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)

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)

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 }

Unterstützte Länder und Formate

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

DEDeutschland

PDFZUGFERD 2.4XRECHNUNG 3.0.2 *

ATÖsterreich

PDFEBINTERFACE *ZUGFERD 2.4

CHSchweiz

PDFQR-BILL *

FRFrankreich

PDFFACTUR-X 1.08 *

ITItalien

PDFFATTURAPA *

ESSpanien

PDFFACTURAE *VERIFACTU QR

NLNiederlande

PDFUBL *

BEBelgien

PDFUBL *

PTPortugal

PDFSAF-TPEPPOL-UBL *

PLPolen

PDFKSEFPEPPOL-UBL *

CZTschechien

PDFISDOC *

HUUngarn

PDFNAV *

RORumänien

PDFEFACTURA *PEPPOL-UBL

BGBulgarien

PDFUBL *

SESchweden

PDFPEPPOL-UBL *

NONorwegen

PDFPEPPOL-UBL *

DKDänemark

PDFPEPPOL-UBL *

FIFinnland

PDFPEPPOL-UBL *

IEIrland

PDFPEPPOL-UBL *

GBGroßbritannien

PDFPEPPOL-UBL *

LULuxemburg

PDFPEPPOL-UBL *

MTMalta

PDFPEPPOL-UBL *

CYZypern

PDFPEPPOL-UBL *

SISlowenien

PDFPEPPOL-UBL *

EEEstland

PDFPEPPOL-UBL *

LVLettland

PDFPEPPOL-UBL *

LTLitauen

PDFPEPPOL-UBL *

GRGriechenland

PDFPEPPOL-UBL *MYDATA

* 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.

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_*)
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

Validator API

Rechnungen validieren

Converter API

Formate konvertieren

Webhooks

Events empfangen

Playground

API interaktiv testen