Core API

Converter API

Konvertiere E-Rechnungen zwischen verschiedenen Formaten ohne Datenverlust. XRechnung, ZUGFeRD, Factur-X und UBL werden bidirektional unterstützt.

POST/v1/convert

Bidirektional

Konvertiere in beide Richtungen zwischen allen unterstützten Formaten

Validiert

Automatische Validierung von Quell- und Zielformat gegen KoSIT-Schemas

PDF inklusive

Bei ZUGFeRD-Konvertierung wird automatisch ein PDF/A-3 generiert

Konvertierungs-Matrix

Von	Nach
XRechnung 3.0	ZUGFeRD 2.1Factur-X 1.0UBL 2.1
XRechnung 2.3	XRechnung 3.0ZUGFeRD 2.1ZUGFeRD 2.0
ZUGFeRD 2.1	XRechnung 3.0Factur-X 1.0UBL 2.1
ZUGFeRD 2.0	ZUGFeRD 2.1XRechnung 3.0
Factur-X 1.0	ZUGFeRD 2.1XRechnung 3.0UBL 2.1
UBL 2.1	XRechnung 3.0ZUGFeRD 2.1Factur-X 1.0

Beispiel

bash

1curl -X POST https://api.xhub.io/v1/convert \
2  -H "Authorization: Bearer xhub_live_abc123..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "xml": "<?xml version=\"1.0\"?>\n<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>",
6    "sourceFormat": "xrechnung-3.0",
7    "targetFormat": "zugferd-2.1"
8  }'

Alternative: Multipart File Upload

bash

1curl -X POST https://api.xhub.io/v1/convert \
2  -H "Authorization: Bearer xhub_live_abc123..." \
3  -H "Content-Type: multipart/form-data" \
4  -F "file=@rechnung.xml" \
5  -F "targetFormat=zugferd-2.1"

Response

json

1{
2  "id": "conv_xyz789abc",
3  "status": "success",
4  "source": {
5    "format": "XRechnung",
6    "version": "3.0.2"
7  },
8  "target": {
9    "format": "ZUGFeRD",
10    "version": "2.1.1",
11    "profile": "EXTENDED"
12  },
13  "validation": {
14    "source": {
15      "valid": true,
16      "errors": 0
17    },
18    "target": {
19      "valid": true,
20      "errors": 0
21    }
22  },
23  "download": {
24    "xml": "https://api.xhub.io/v1/conversions/conv_xyz789abc/xml",
25    "pdf": "https://api.xhub.io/v1/conversions/conv_xyz789abc/pdf"
26  },
27  "processingTime": 230
28}

Request Parameter

Parameter	Typ	Pflicht	Beschreibung
`xml`	string		Die zu konvertierende XML-Rechnung
`sourceFormat`	string	-	Quellformat. Wird automatisch erkannt wenn nicht angegeben
`targetFormat`	string		Zielformat der Konvertierung
`profile`	string	-	ZUGFeRD-Profil: MINIMUM, BASIC, BASIC-WL, EN16931, EXTENDED (Default: EN16931)
`validateSource`	boolean	-	Quell-XML vor Konvertierung validieren (Default: true)
`validateTarget`	boolean	-	Ziel-XML nach Konvertierung validieren (Default: true)

Format-Werte

xrechnung-3.0

XRechnung 3.0.2

xrechnung-2.3

XRechnung 2.3

zugferd-2.1

ZUGFeRD 2.1.1

zugferd-2.0

ZUGFeRD 2.0.1

factur-x-1.0

Factur-X 1.0

ubl-2.1

UBL 2.1 (OASIS)

ZUGFeRD Profile

Bei Konvertierung nach ZUGFeRD kannst du das Profil festlegen. Das Profil bestimmt, welche Felder im XML enthalten sind.

MINIMUM

Nur Pflichtfelder, für einfache Rechnungen

BASIC

Basis-Informationen für automatische Verarbeitung

BASIC-WL

BASIC ohne Positionen (Rechnungssummen only)

EN16931

EU-Norm, empfohlen für B2G (Default)

EXTENDED

Alle Felder, maximale Detailtiefe

ZUGFeRD PDF-Generierung

Bei Konvertierung zu ZUGFeRD wird automatisch ein PDF/A-3 erstellt, in dem das XML eingebettet ist. Das PDF verwendet ein Standard-Layout. Für individuelle PDF-Designs nutze die Visualizer API (Coming Soon).

Typische Anwendungsfälle

XRechnung → ZUGFeRD

Du hast XRechnungen für Behörden erstellt und willst dieselben Rechnungen als PDF mit eingebettetem XML an Geschäftskunden senden.

ZUGFeRD → XRechnung

Du erhältst ZUGFeRD-Rechnungen von Lieferanten und musst diese zur Weiterverarbeitung in XRechnung konvertieren.

XRechnung 2.3 → 3.0

Migration bestehender XRechnungen auf die aktuelle Version 3.0 für die Kompatibilität mit aktuellen Behörden-Systemen.

Factur-X → XRechnung

Französische Factur-X Rechnungen für den deutschen Markt aufbereiten und an öffentliche Auftraggeber senden.

Weiterführende Dokumentation

Creator API

Rechnungen erstellen

Validator API

Rechnungen validieren

Error Handling

Fehler verstehen

Playground

API interaktiv testen