Converter API
Eine bestehende E-Rechnung in ein anderes Format umwandeln: Quelle hinein (XML oder PDF), Zielformat wählen, fertiges Dokument zurück. Das Quellformat wird erkannt; Felder, die das Zielformat nicht führt, werden als conversionWarnings ausgewiesen.
/api/v1/invoice/convertUnterschied zu parse + generate
Dasselbe Ergebnis lässt sich mit zwei Aufrufen bauen: parse liefert das kanonische invoice-JSON, generate erzeugt daraus das Zielformat. convert macht daraus einen Aufruf — und gibt zwei Angaben zurück, die der Zweiweg nicht hat: sourceFormat, den erkannten Quellbeleg, und conversionWarnings, die Felder, die die Quelle trug und das Zieldokument nicht führt. Abgerechnet wird wie ein generate: der Aufruf braucht die parse-Berechtigung des Quellformats und die create-Berechtigung des Zielformats und zählt einmal auf das Kontingent des Ziels.
Quellformat wird erkannt
Kein sourceFormat im Request: Format und Land werden aus dem Dokument bestimmt. Lässt sich das nicht sicher entscheiden, antwortet der Dienst mit 400 FORMAT_NOT_DETECTED statt zu raten.
Das Ziel wird geprüft
Das erzeugte Dokument wird gegen die Regeln des Zielformats geprüft. Bricht es eine, kommt 422 mit den Regelcodes (z. B. BR-DE-6) — statt eines Dokuments, das der Empfänger ablehnt.
PDF/A-3 inklusive
Bei zugferd und facturx entsteht ein PDF/A-3 mit eingebettetem CII-XML: mimeType ist application/pdf, data die Base64-Datei.
Konvertierungs-Matrix
Als Quelle kommt jeder Beleg in Frage, den der Parser erkennt — XML oder ZUGFeRD/Factur-X-PDF. Als Ziel gibt es genau drei Werte; jeder andere wird mit 400 und der Liste der erlaubten Werte abgewiesen.
| Von (erkannt) | Nach (targetFormat) |
|---|---|
| XRechnung 3.x (UBL / CII) | zugferdfacturxxrechnung |
| XRechnung 2.x | zugferdfacturxxrechnung |
| ZUGFeRD / Factur-X (PDF/A-3) | zugferdfacturxxrechnung |
| EN 16931 UBL / CII XML | zugferdfacturxxrechnung |
Die Richtung nach xrechnung ist nicht symmetrisch: XRechnung → ZUGFeRD ist verlustfrei (CIUS → EN 16931), der Rückweg gelingt nur, wenn die deutschen Pflichtangaben im Quellbeleg stehen. Gemessen am 2026-09-15 scheiterte er an BR-DE-6 — der Telefonnummer des Verkäufers (BT-42), die ZUGFeRD nicht verlangt. Dieselbe Klasse trifft die Leitweg-ID (BT-10) bei Belegen an öffentliche Auftraggeber.
Beispiel
1curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/convert \2 -H "Authorization: Bearer sk_live_abc123..." \3 -H "Content-Type: application/json" \4 -d '{5 "source": "<?xml version=\"1.0\"?>\n<ubl:Invoice xmlns:ubl=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</ubl:Invoice>",6 "targetFormat": "zugferd"7 }'Alternative: Quelle als Base64 (PDF oder XML)
1# Same endpoint, base64 source — this is the form to use for a2# ZUGFeRD/Factur-X PDF, because a PDF is not a text body.3curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/convert \4 -H "Authorization: Bearer sk_live_abc123..." \5 -H "Content-Type: application/json" \6 -d "{\"source\": \"$(base64 -i rechnung-zugferd.pdf)\", \"targetFormat\": \"xrechnung\"}"Response
Erfolg
200 OKGemessene Antwort für XRechnung (UBL) → ZUGFeRD. data ist das Base64-Dokument, hash der SHA-256 darüber (ohne Präfix), filename die Rechnungsnummer mit der Endung des Zielformats. sourceFormat ist der erkannte Quellbeleg — nicht etwas, das der Aufruf mitgeschickt hätte.
1{2 "success": true,3 "sourceFormat": "XRECHNUNG_UBL",4 "targetFormat": "zugferd",5 "mimeType": "application/pdf",6 "filename": "RE-2025-001.pdf",7 "hash": "137429b56d6d01de076e7c03369df3c33218d98e688ea93b4b7b4fb97b20aa13",8 "data": "JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0xlbmd0aCAxODA1...",9 "conversionWarnings": []10}Ziel nicht konform
422Gemessene Antwort für den Rückweg: dasselbe ZUGFeRD-PDF nach xrechnung. complianceErrors nennt die verletzten Regeln — die Angabe, mit der sich der Quellbeleg reparieren lässt.
1{2 "success": false,3 "error": "CONVERSION_FAILED",4 "message": "The source could not be converted to a conformant target document",5 "targetFormat": "xrechnung",6 "complianceErrors": [7 {8 "code": "BR-DE-6",9 "message": "[BR-DE-6] Das Element \"Seller contact telephone number\" (BT-42) muss übermittelt werden.",10 "field": ".../AccountingSupplierParty[1]/Party[1]/Contact[1]"11 }12 ],13 "conversionWarnings": []14}Request Parameter
| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
source | string | Der Quellbeleg: rohes XML (der String beginnt mit „<“) oder Base64 einer XML- oder PDF-Datei. | |
targetFormat | string | Zielformat: zugferd, facturx oder xrechnung. | |
options.zugferdProfile | string | - | CII-Profil für zugferd und facturx: BASIC, EN16931 (Vorgabe) oder EXTENDED. |
Mehr Felder gibt es nicht. Ältere Fassungen dieser Seite zeigten xml, sourceFormat, profile, validateSource, validateTarget und einen Multipart-Upload — der Endpunkt kennt keines davon.
Zielformat-Werte
xrechnungXRechnung 3.0.2 (UBL XML)
zugferdZUGFeRD 2.x (PDF/A-3)
facturxFactur-X 1.0.x (PDF/A-3)
ZUGFeRD und Factur-X bezeichnen denselben deutsch-französischen Hybrid-Standard (PDF/A-3 mit eingebettetem EN-16931-XML). Welche Ausprägung entsteht, entscheidet das Land des Verkäufers (FR/BE → Factur-X, sonst ZUGFeRD) — beide Werte liefern deshalb dasselbe PDF. Ältere Versionen werden als Quelle erkannt; Ziel ist immer die aktuelle Version.
ZUGFeRD-Profile
Bei zugferd und facturx bestimmt das Profil, welche Felder im eingebetteten XML landen. Ohne Angabe wird EN16931 verwendet.
BASICBasis-Informationen für automatische Verarbeitung
EN16931EU-Norm, empfohlen für B2G (Vorgabe)
EXTENDEDAlle Felder, maximale Detailtiefe
MINIMUM und BASIC WL sind über die API nicht anforderbar: beide führen keine Rechnungspositionen, sind nicht EN-16931-konform und gelten laut Spezifikation als Buchungshilfe. Wer sie anfordert, bekommt 400 mit den drei zulässigen Profilen. Empfangen und parsen lassen sich solche Belege weiterhin.
Fehlerfälle
| Status | Code | Beschreibung |
|---|---|---|
| 400 | Bad Request | source oder targetFormat fehlt, oder targetFormat ist keiner der drei Werte. Auch ein zurückgezogenes Profil (MINIMUM, BASIC WL) wird hier abgewiesen. |
| 400 | FORMAT_NOT_DETECTED | Das Quellformat ließ sich nicht sicher bestimmen; die Antwort enthält das detection-Objekt mit der Konfidenz. |
| 403 | FORBIDDEN | Es fehlt eine Berechtigung — gebraucht werden die parse-Berechtigung des erkannten Quellformats und die create-Berechtigung des Zielformats. |
| 422 | CONVERSION_FAILED | Das Zieldokument wäre nicht konform; complianceErrors nennt die Regeln. |
| 429 | QUOTA_EXCEEDED | Das Kontingent des Ziel-Schlüssels ist erschöpft. |
Für die Zahl der Rechnungspositionen gilt beim Umwandeln dieselbe tarifabhängige Grenze wie beim Erzeugen — darüber antwortet die API mit HTTP 400 und TOO_MANY_LINE_ITEMS: Grenzen in der Creator-API
Layout des erzeugten PDFs
Bei zugferd und facturx entsteht das PDF aus einer Standard-Vorlage; maßgeblich ist das eingebettete XML. Für ein eigenes Layout ist die Visualizer API Geplant Q4/2026
Typische Anwendungsfälle
Du hast XRechnungen für Behörden erstellt und willst dieselben Rechnungen als PDF mit eingebettetem XML an Geschäftskunden senden.
Du erhältst ZUGFeRD-Rechnungen von Lieferanten und brauchst sie als XRechnung — das gelingt, wenn der Quellbeleg die deutschen Pflichtangaben trägt.
Bestehende XRechnungen auf die aktuelle Version bringen: die alte Fassung wird als Quelle erkannt, Ziel ist immer die aktuelle.
Französische Factur-X-Rechnungen für den deutschen Markt aufbereiten und an öffentliche Auftraggeber senden.