Zum Hauptinhalt springen

Integration

Markdown-Export

Externe API V1 Dokumentation

Wandeln Sie Rechnungen direkt aus Ihren Systemen in validierte E-Rechnungen um: Laden Sie ein PDF-, DOCX- oder TXT-Dokument – oder strukturierte ERP-Daten – hoch und laden Sie nach bestandener Validierung XRechnung-, ZUGFeRD-, EN-16931-, UBL- oder CII-Ausgaben herunter. Diese Seite ist der vollständige Integrationsvertrag: Zugangsmodell, Endpunkte, Fehlerkatalog und Limits.

Fünf REST-Endpunkte machen aus PDF-, DOCX- oder TXT-Rechnungen – oder strukturierten ERP-Daten – validierte XRechnung-, ZUGFeRD-, EN-16931-, UBL- und CII-E-Rechnungen. Aktive Enterprise-Kunden erstellen Schlüssel direkt; monatlich sind 100 gemeinsame E-Mail/API-Konvertierungen enthalten, danach kostet jede Konvertierung 0,40–0,50 € in Prepaid-Credits.

Überblick

Die API akzeptiert Multipart-Uploads, liefert JSON-Antworten und nutzt Standard-HTTP-Statuscodes mit Bearer-Authentifizierung. Jede Umwandlung läuft asynchron: Dokument senden, Task abfragen, Ergebnis herunterladen. Eine Datei wird erst nach bestandener Validierung ausgeliefert – unvalidierte Ausgaben gibt es nicht.

Senden Sie ein PDF-, DOCX- oder TXT-Rechnungsdokument oder strukturierte Rechnungsdaten an einen Konvertierungsendpunkt. Invoice-Converter startet daraus einen asynchronen Task für Extraktion, Validierung und Artefakterzeugung. Der Ergebnisendpunkt liefert eine Datei nur, wenn das angeforderte Artefakt validiert, geprüft und ausgabebereit ist; während der Verarbeitung liefert er 202 TASK_NOT_READY, bei blockierenden Validierungsfehlern 422 VALIDATION_FAILED.

Status: Enterprise-Zugang

Basispfad: /api/v1. Zuletzt synchronisiert 2026-09-08.

Wichtige Funktionen

  • Upload-Endpunkte für PDF-Rechnungen und strukturierte Rechnungsdaten
  • Extraktion von Rechnungsdaten mit Abgleich der Felder zur Quelle
  • Automatisierte EN 16931- und KoSIT-Validierung
  • Ausgabeformate XRechnung, ZUGFeRD, EN16931, UBL und CII
  • Asynchrone Verarbeitung mit Polling; kleine Rechnungen dauern oft ca. 30 Sekunden, größere bis zu 1-2 Minuten
  • Idempotente Schreibzugriffe für sichere Wiederholungen

Enterprise-API-Zugang starten

Jeder aktive Enterprise-Kunde kann produktive API-Schlüssel direkt im Profil erstellen.

  1. Erstellen Sie ein Konto und starten Sie Enterprise auf der Preisseite: 35 €/Monat bei jährlicher Abrechnung (420 €/Jahr); bei monatlicher Abrechnung: 50 €/Monat.
  2. Nutzen Sie die 100 monatlich enthaltenen gemeinsamen E-Mail/API-Konvertierungen; weitere Konvertierungen kosten über Prepaid-Credits je 0,40–0,50 €.
  3. Erstellen Sie im API-Bereich Ihres Profils einen Live-API-Schlüssel.
  4. Senden Sie die erste Anfrage mit Bearer-Token und stabilem Idempotency-Key.

Schnellstart

Drei API-Aufrufe schließen eine Konvertierung ab. Der Convert-Endpoint wird unter /api/v1 bereitgestellt und erfordert Authentifizierung.

POST /api/v1/invoices:convert

Live

Rechnungsdokument konvertieren

POST /api/v1/invoices:convert-structured

Live

Strukturierte Daten konvertieren

GET /api/v1/tasks/{task_id}

Live

Task-Status abfragen

Schnellstart mit curl

Ersetzen Sie $API_KEY durch Ihren Live-Schlüssel und $TASK_ID durch die task_id aus der ersten Antwort. Dieselben drei Aufrufe funktionieren für jedes Ausgabeformat.

1. Umwandlung starten
curl -X POST "https://www.invoice-converter.com/api/v1/invoices:convert" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: inv-2026-0001" \
  -F "file=@invoice.pdf" \
  -F "format=XRECHNUNG"
2. Task bis completed abfragen
curl "https://www.invoice-converter.com/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
3. Validierte Datei herunterladen
curl -o invoice.xml \
  "https://www.invoice-converter.com/api/v1/tasks/$TASK_ID/result?download=xml" \
  -H "Authorization: Bearer $API_KEY"

Basis-URL und API-Schlüssel

  • Produktive Basis-URL: https://www.invoice-converter.com/api/v1.
  • Live-API-Schlüssel nutzen den Produktions-Host und das Präfix icp_....
  • Nutzen Sie Ihren Live-Schlüssel für Onboarding und Validierungsläufe, bevor Sie Produktionsvolumen senden.
  • Behandeln Sie API-Schlüssel als serverseitige Secrets. Betten Sie sie nicht in Browser- oder Mobile-Clients ein.

Erste erfolgreiche Anfrage

Nutzen Sie diese Sequenz als minimalen Happy Path nach Erstellung eines API-Schlüssels.

  • Hochladen: POST /api/v1/invoices:convert mit Authorization, Idempotency-Key, file=@invoice.pdf (oder .docx/.txt) und format=XRECHNUNG.
  • Mit Backoff pollen: nach dem 202 etwa 20 Sekunden warten, dann GET /api/v1/tasks/{task_id} in Abständen von 20s, 30s, 45s, 60s und 60s aufrufen, bis der Status completed oder failed ist. Bleiben Sie im Kontingent von 10/min und 120/hour und brechen Sie nach etwa 16 Minuten ab.
  • Herunterladen: GET /api/v1/tasks/{task_id}/result?download=xml; speichern Sie X-Correlation-ID für den Support-Trace.
  • Für ZUGFeRD-PDF-Ausgabe beim Convert format=ZUGFERD und beim Result download=pdf anfragen; Hybrid-PDF-Ausgabe erfordert einen PDF-Quellupload.
  • Für strukturierte Eingaben rufen Sie POST /api/v1/invoices:convert-structured mit pdf_file=@invoice.pdf, data_file=@invoice-data.json und dem Ziel-format auf.
  • Optional client_reference oder external_invoice_id und source_system für ERP-Abgleich senden.
  • Bei gesplitteten ERP-Exporten einer Rechnung wiederholen Sie data_file; bei mehreren Rechnungen starten Sie pro Rechnung einen Task mit eigenem Idempotency-Key.
  • Speichern Sie result_artifacts aus der Statusantwort, um zu sehen, ob XML/PDF-Artefakte validiert, zwischengespeichert oder wegen Abhängigkeiten noch nicht verfügbar sind.

Häufige Payload-Beispiele

  • XRECHNUNG: format=XRECHNUNG senden.
  • ZUGFERD: format=ZUGFERD senden; für hybrides PDF/A-3 im Result download=pdf nutzen.
  • Strukturierte Eingabe: pdf_file plus ein oder mehrere data_file-Parts senden; akzeptierte Datenformate sind CSV, JSON, XML, XLSX und TXT, mit jedem unterstützten Zielformat. Die data_file-Parts müssen alle Pflichtdaten enthalten; das PDF ergänzt keine fehlenden Felder.
  • Mehrere Rechnungen: separate Convert-Requests senden und jede zurückgegebene task_id nachverfolgen; wiederholte data_file-Parts sind nur für gesplittete Exporte derselben Rechnung gedacht.
  • UBL: format=UBL senden; zulässige Profile sind XRECHNUNG, PEPPOL und EN16931, Standard ist EN16931.
  • CII: format=CII senden; zulässige Profile sind XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED und ZUGFERD_XRECHNUNG, Standard ist EN16931.
  • format x profile ist eine abgeschlossene Tabelle: XRECHNUNG akzeptiert [XRECHNUNG] (Standard XRECHNUNG), EN16931 akzeptiert [EN16931] (Standard EN16931), UBL akzeptiert [XRECHNUNG, PEPPOL, EN16931] (Standard EN16931), CII akzeptiert [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (Standard EN16931) und ZUGFERD akzeptiert [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (Standard ZUGFERD_EN16931). Profile werden ohne Beachtung der Groß-/Kleinschreibung zugeordnet; ZUGFERD, FACTURX, FACTUR-X und FACTUR_X sind Aliase für ZUGFERD_EN16931, ZUGFERD-XRECHNUNG ist ein Alias für ZUGFERD_XRECHNUNG.

Erforderliche Header

  • Authorization: Bearer <api_key>

Auth-Regeln

Jeder aktive Enterprise-Kunde kann im Profil API-Schlüssel erstellen und als Bearer-Token verwenden. Das gemeinsame E-Mail/API-Kontingent umfasst 100 Konvertierungen pro Monat; weitere Konvertierungen kosten über Prepaid-Credits je 0,40–0,50 €.

  • API-Schlüssel sind tenant-gebundene Live-Zugangsdaten für aktive Enterprise-Abonnements. Das aktuelle Produktionspräfix ist icp_....
  • Erstellen, rotieren und widerrufen Sie API-Schlüssel im Profil, solange Enterprise aktiv ist. Kopieren Sie neue Schlüssel sofort, da Klartextschlüssel nur einmal angezeigt werden.
  • Fehlende oder ungültige API-Schlüssel liefern 401.
  • Aufrufe an /api/v1 erhalten automatisch eine X-Correlation-ID, wenn sie fehlt.
  • Schreibaufrufe erfordern Idempotency-Key; halten Sie diesen Wert über Retries stabil.
  • Verwenden Sie Server-zu-Server-Integration aus Ihrem Backend. Browser-Origin-Zugriff ist in Produktion eingeschränkt.

Idempotenz-Vertrag

  • Senden Sie bei jedem Schreibaufruf einen Idempotency-Key.
  • Idempotency-Key-Werte müssen [A-Za-z0-9._:-]+ entsprechen und höchstens 200 Zeichen lang sein.
  • Bei eigenem Key liefert derselbe Key + identischer Payload die zwischengespeicherte Antwort.
  • Derselbe Key + anderer Payload liefert 409 IDEMPOTENCY_CONFLICT; das ist nicht wiederholbar — verwenden Sie für einen neuen Payload einen neuen Key.
  • Ein zweiter Request mit demselben Key, während der erste noch läuft, liefert 409 IDEMPOTENCY_IN_PROGRESS; senden Sie denselben Key nach kurzer Wartezeit erneut. Ein hängender In-Progress-Anspruch wird nach 15 Minuten freigegeben.
  • Ist der ursprüngliche Task über seine 24-Stunden-Aufbewahrung hinaus, liefert ein Replay 409 IDEMPOTENCY_REPLAY_EXPIRED; starten Sie eine neue Konvertierung mit einem neuen Key.
  • Idempotenz-Datensätze bestehen 24 Stunden und entsprechen damit der Task-Aufbewahrung.

Endpunkt-Referenz

Alle Endpunkte sind unter /api/v1 erreichbar. Timeouts erscheinen als 504 und andere temporäre Verbindungsfehler als 502; Korrelations-IDs helfen dem Support bei der Nachverfolgung über den gesamten Ablauf.

POST /api/v1/invoices:convert

Live

Laden Sie ein PDF-, DOCX- oder TXT-Rechnungsdokument hoch und starten Sie die asynchrone Konvertierung. Gibt eine task_id für das Polling zurück. ZUGFeRD/Factur-X-Hybrid-PDFs erfordern einen PDF-Quellupload; für DOCX/TXT-Quellen sollten XML-Ergebnisse angefragt werden. Eingebettete Rechnungs-XML wird standardmäßig ignoriert; setzen Sie use_embedded_xml=true nur, wenn Ihre Integration sie als primäre Extraktionsquelle akzeptiert. Anfrage: multipart/form-data; file (binary, erforderlich) — PDF-, DOCX- oder TXT-Rechnungsdokument; alte DOC/RTF-, Bild- und andere Dateien werden abgelehnt; format (string, erforderlich) — Zielausgabeformat; siehe Formatmatrix unten; profile (string, optional, empfohlen für deterministische Integrationen) — explizites Compliance-Profil, Groß-/Kleinschreibung wird ignoriert. Jedes Format hat eine abgeschlossene Menge zulässiger Profile und genau einen Standard: XRECHNUNG → [XRECHNUNG] (Standard XRECHNUNG); EN16931 → [EN16931] (Standard EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (Standard EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (Standard EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (Standard ZUGFERD_EN16931). ZUGFERD, FACTURX, FACTUR-X und FACTUR_X sind Aliase für ZUGFERD_EN16931; ZUGFERD-XRECHNUNG ist ein Alias für ZUGFERD_XRECHNUNG. Ein Wert außerhalb der zulässigen Menge liefert 422 OUTPUT_PROFILE_CONFLICT; ein nicht erkannter Profilname liefert 422 INVALID_PROFILE mit details.allowed_profiles; jurisdiction (string, optional) — expliziter ISO-3166-1-Alpha-2-Jurisdiktionskontext für Validierungs-/Hinweisprüfungen; überschreibt das Profil nicht; transaction_scope (string, optional) — expliziter Transaktionskontext, zum Beispiel B2G; wird auf die eingereihte Aufgabe angewendet; delivery_channel (string, optional) — einer von PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; wird auf die eingereihte Aufgabe angewendet; client_reference oder external_invoice_id (string, optional) — kundenseitige Rechnungs-/Jobreferenz, die in angenommenen Uploads und Task-Statusantworten zurückgegeben wird; source_system (string, optional) — vorgelagertes ERP- oder Abrechnungssystem, das in angenommenen Uploads und Task-Statusantworten zurückgegeben wird; email_input (Freitext, optional, nur PDF-Quellen) — Kundenanweisungen in beliebiger Sprache, bis zu 10.000 Zeichen, ohne E-Mail-Blockmarkierungen übergeben; alle KI-Extraktions- und Korrekturschritte erhalten sie getrennt vom Rechnungsquelltext; nicht mit use_embedded_xml=true kombinierbar, Teil der Request-Identität für Idempotenz und von invoices:convert-structured nicht unterstützt; die normale Rechnungsvalidierung gilt weiterhin; use_seller_master_data (boolean, optional) — ohne Angabe gilt der Standard aus dem Tenant-Profil; false ignoriert gespeicherte Verkäufer-Stammdaten für diesen Request, true stellt Verkäufer-Stammdaten bereit bzw. nutzt sie; seller_master_data (JSON-Objekt-String, optional) — request-bezogene Verkäufer-Stammdaten, die nur bei use_seller_master_data=true verwendet werden; unterstützt werden Firmen-, Adress-, Steuer-, Kontakt- und Zahlungsfelder (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); jeder Profilwert ersetzt den entsprechenden extrahierten Wert, nicht gesetzte Profilfelder bleiben unverändert und Abweichungen erzeugen nicht blockierende Warnungen; electronic_address und electronic_address_scheme müssen gemeinsam gesetzt oder beide weggelassen werden; use_embedded_xml (boolean, optional, Standard false) — eingebettete Factur-X-, ZUGFeRD- oder XRechnung-XML wird ignoriert, außer der Wert ist ausdrücklich true; nur verwenden, wenn die Integration die eingebettete XML als primäre Extraktionsquelle akzeptiert. Antwort: 202 Accepted.

POST /api/v1/invoices:convert-structured

Live

Laden Sie ein Träger-PDF plus CSV-, JSON-, XML-, XLSX- oder TXT-Rechnungsdaten hoch und starten Sie die asynchrone Konvertierung aus strukturierten Daten. Die data_file-Parts sind die einzige semantische Quelle; das PDF füllt keine fehlenden Rechnungsfelder auf. Für ZUGFeRD/Factur-X wird es als Träger-PDF verwendet, bei XML-orientierten Ausgaben als eingereichtes PDF-Artefakt gespeichert. Nutzen Sie einen Konvertierungsrequest pro Rechnung; wiederholen Sie data_file nur für gesplittete ERP-Exporte derselben Rechnung. Anfrage: multipart/form-data; pdf_file (binary, erforderlich) — Träger-PDF für ZUGFeRD/Factur-X-Einbettung und Speicherung bei XML-orientierten Ausgaben; data_file (binary, erforderlich, wiederholbar) — CSV-, JSON-, XML-, XLSX- oder TXT-Rechnungsdaten als einzige semantische Quelle; .xls, PDFs und Bilddateien werden als data_file abgelehnt; für gesplittete Header-/Positions-Exporte derselben Rechnung wiederholen; die Aliasse data_files und data_files[] werden akzeptiert; Gesamtgröße strukturierter Daten — maximal 2 MB über alle data_file-Parts; format (string, erforderlich) — Ziel-Ausgabeformat; unterstützt XRECHNUNG, ZUGFERD, EN16931, UBL und CII; profile (string, optional, empfohlen für deterministische Integrationen) — explizites Compliance-Profil, Groß-/Kleinschreibung wird ignoriert. Jedes Format hat eine abgeschlossene Menge zulässiger Profile und genau einen Standard: XRECHNUNG → [XRECHNUNG] (Standard XRECHNUNG); EN16931 → [EN16931] (Standard EN16931); UBL → [XRECHNUNG, PEPPOL, EN16931] (Standard EN16931); CII → [XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (Standard EN16931); ZUGFERD → [ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG] (Standard ZUGFERD_EN16931). Ein Wert außerhalb der zulässigen Menge liefert 422 OUTPUT_PROFILE_CONFLICT; ein nicht erkannter Profilname liefert 422 INVALID_PROFILE mit details.allowed_profiles; jurisdiction (string, optional) — expliziter ISO-3166-1-Alpha-2-Jurisdiktionskontext für Validierungs-/Hinweisprüfungen; überschreibt das Profil nicht; transaction_scope (string, optional) — expliziter Transaktionskontext, zum Beispiel B2G; wird auf die eingereihte Aufgabe angewendet; delivery_channel (string, optional) — einer von PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, UNKNOWN; wird auf die eingereihte Aufgabe angewendet; client_reference oder external_invoice_id (string, optional) — kundenseitige Rechnungs-/Jobreferenz, die in angenommenen Uploads und Task-Statusantworten zurückgegeben wird; source_system (string, optional) — vorgelagertes ERP- oder Abrechnungssystem, das in angenommenen Uploads und Task-Statusantworten zurückgegeben wird; use_seller_master_data (boolean, optional) — ohne Angabe gilt der Standard aus dem Tenant-Profil; false ignoriert gespeicherte Verkäufer-Stammdaten für diesen Request, true stellt Verkäufer-Stammdaten bereit bzw. nutzt sie; seller_master_data (JSON-Objekt-String, optional) — request-bezogene Verkäufer-Stammdaten, die nur bei use_seller_master_data=true verwendet werden; unterstützt werden Firmen-, Adress-, Steuer-, Kontakt- und Zahlungsfelder (payment_means_code 30/42/58, payment_iban, payment_bic, payment_account_name, payment_terms_note); jeder Profilwert ersetzt den entsprechenden extrahierten Wert, nicht gesetzte Profilfelder bleiben unverändert und Abweichungen erzeugen nicht blockierende Warnungen; electronic_address und electronic_address_scheme müssen gemeinsam gesetzt oder beide weggelassen werden. Antwort: 202 Accepted.

GET /api/v1/tasks/{task_id}

Live

Fragen Sie den aktuellen Status eines Konvertierungs-Tasks ab. Gibt pending (angenommen und in der Queue, noch nicht gestartet), processing, completed oder failed zurück. Rate-Limit 10/min und 120/hour; das ist die bindende Grenze für das Polling: Warten Sie nach dem angenommenen 202 etwa 20 Sekunden bis zum ersten Aufruf, erhöhen Sie danach die Abstände (20s, 30s, 45s, 60s und ab dann 60s) und beenden Sie das Polling bei completed oder failed. Abgeschlossene Tasks enthalten result_artifacts-Diagnosen, damit Clients sehen können, welche XML/PDF-Artefakte verfügbar, im Cache gespeichert und durch Validierung verifiziert sind. Payloads abgeschlossener Tasks können zusätzliche _processing_warnings- und _validation_warnings-Einträge mit SOURCE_CONTEXT_*-Regel-IDs enthalten, wenn Quellenbelege fehlten, zweifelhaft oder abgeschnitten waren; behandeln Sie diese als Prüfsignale, nicht als Fehler. Bei failed enthält die Antwort ein error-Feld mit dem Fehlergrund. Anfrage: keins (GET); task_id (path, erforderlich) — UUID, die vom Convert-Endpoint zurückgegeben wurde; include_validation_report_html (query, optional) — true oder false (Standard false); bei true enthält die Statusantwort den bereinigten HTML-Validierungsbericht des aktuellen strikten Artefakts, sofern verfügbar. Antwort: 200 OK.

GET /api/v1/tasks/{task_id}/result

Live

Laden Sie die erzeugte Datei herunter (XML oder PDF). Die Ergebnissyntax entspricht dem ursprünglichen Task-Format: XRECHNUNG/EN16931/UBL liefern UBL-XML, CII/ZUGFERD liefern CII-XML, und ZUGFERD + download=pdf liefert ein hybrides PDF/A-3. Bei anderen Formaten kann download=pdf ein gerendertes PDF liefern; bei einem abgeschlossenen Task ist download=xml das erwartbar verfügbare Artefakt, aber kein garantiertes. Wiederholte Downloads können aus zwischengespeicherten Artefakten bedient werden, wenn der Validierungsnachweis noch aktuell ist. Während der Verarbeitung liefert der Endpunkt ein 202 mit dem Standard-Fehlerumschlag ({"code":"TASK_NOT_READY","message":"Strict conversion is still processing. No validated artifact is available yet.","correlation_id":"<uuid>"}); blockierende Validierungsfehler liefern 422 VALIDATION_FAILED, wiederholbare Abhängigkeitslücken 503, endgültige Konvertierungsfehler 500 TASK_FAILED mit dem Grund in details.code und Artefakt-Invariantfehler 500 INTERNAL_ARTIFACT_INVARIANT_FAILED — jeweils ohne Dateiinhalt. Erfolgreiche Downloads enthalten X-Correlation-ID, Content-Disposition, Cache-Control: no-store, X-Artifact-Sha256, X-Validation-Proof-Id, X-Artifact-Proof-Id, X-Artifact-State, X-Validation-State, X-Proof-Status und X-Validator-Bundle-Id; X-Task-Id wird an diesem Endpunkt nicht gesetzt. Rate-Limit 10/min und etwa 134/hour. Anfrage: keins (GET); task_id (path, erforderlich) — UUID, die vom Convert-Endpoint zurückgegeben wurde; download (query, erforderlich) — xml oder pdf. Antwort: 200 OK.

GET /api/v1/tasks/{task_id}/validation-report

Live

Laden Sie den Bericht zum aktuell validierten Ergebnisartefakt herunter. Der Bericht ist erst verfügbar, nachdem die strikte Konvertierung ein Artefakt mit aktuellem Nachweis gespeichert hat; sonst liefert der Endpunkt 202 oder 404. Antwort-Header identifizieren Artefakt und Berichtsnachweis. X-Artifact-Sha256 bezeichnet das Ergebnisartefakt, nicht die Berichtsdatei. Rate-Limit: 10/min und 120/Stunde. Anfrage: keins (GET); task_id (Pfad, erforderlich) — UUID, die ein Konvertierungsendpunkt zurückgibt; download (Abfrage, optional) — html oder xml. Antwort: 200 OK.

Ausgabeformat-Matrix

FormatSyntaxVersion / ProfilContent-TypeDateiendung
XRECHNUNGUBL 2.1 XMLXRechnung 3.0.2application/xml.xml
ZUGFERDCII-XML (download=xml) / hybrides PDF/A-3 (download=pdf)ZUGFeRD 2.5 / Factur-X 1.09application/xml oder application/pdf.xml / .pdf
EN16931UBL 2.1 XMLEN 16931application/xml.xml
UBLUBL 2.1 XMLOASIS UBL 2.1application/xml.xml
CIIUN/CEFACT CII XMLD16Bapplication/xml.xml

Fehlervertrag

CodeHTTPWiederholbarHinweise
AUTHENTICATION_REQUIRED401NeinFehlender/leerer Bearer-Token
INVALID_API_KEY401NeinAPI-Schlüssel nicht gefunden, widerrufen oder abgelaufen
API_NOT_ENABLED_FOR_TENANT403NeinDer Schlüssel ist gültig, aber der External-API-Zugang ist für dieses Konto deaktiviert; Support kontaktieren
INSUFFICIENT_API_CREDITS402NeinEnthaltenes Monatskontingent plus Prepaid-API-Credits reichten für den Request nicht aus. Zwei details-Formen: Prepaid (remaining, minimum_purchase 100) und enthaltenes Kontingent (included_remaining, credit_remaining, shortfall, minimum_purchase 100). Werten Sie den code aus und lesen Sie die jeweils vorhandenen Schlüssel
IDEMPOTENCY_KEY_REQUIRED400NeinSchreibendpunkt ohne Idempotency-Key aufgerufen
INVALID_IDEMPOTENCY_KEY400NeinIdempotency-Key muss [A-Za-z0-9._:-]+ entsprechen und darf höchstens 200 Zeichen lang sein
IDEMPOTENCY_CONFLICT409NeinDer Key wurde bereits mit einem anderen Payload verwendet, oder der idempotente Anspruch konnte nicht gestartet werden; für einen neuen Payload einen neuen Key verwenden
IDEMPOTENCY_IN_PROGRESS409JaDer erste Request mit diesem Key läuft noch; denselben Key nach kurzer Wartezeit erneut senden. Ein hängender In-Progress-Anspruch wird nach 15 Minuten freigegeben
IDEMPOTENCY_REPLAY_EXPIRED409NeinDer ursprüngliche Task liegt außerhalb der 24-Stunden-Aufbewahrung; neue Konvertierung mit neuem Schlüssel starten
FORMAT_REQUIRED400NeinKonvertierungsrequest ohne erforderliches format
INVALID_FORMAT422NeinNicht unterstütztes Konvertierungsformat
CLIENT_REFERENCE_CONFLICT400Neinclient_reference und external_invoice_id unterscheiden sich
INVALID_CLIENT_METADATA400Neinclient_reference, external_invoice_id oder source_system überschreitet das Längenlimit oder enthält Steuerzeichen
INVALID_EMAIL_INPUT400Neinemail_input wird mehr als einmal gesendet, überschreitet 10.000 Zeichen, wird mit einer Nicht-PDF-Quelle oder use_embedded_xml=true kombiniert oder an invoices:convert-structured gesendet
INVALID_EMBEDDED_XML_POLICY400Neinuse_embedded_xml muss true oder false sein
INVALID_SELLER_MASTER_DATA400Neinuse_seller_master_data oder seller_master_data ist nicht parsebar oder besteht die Feldvalidierung nicht; electronic_address und electronic_address_scheme müssen gemeinsam gesetzt oder beide weggelassen werden
METHOD_NOT_ALLOWED405NeinKonvertierungspfade akzeptieren nur POST und Task-Pfade nur GET; die Antwort enthält Allow: POST, OPTIONS (Konvertierung) bzw. Allow: GET, OPTIONS (Task)
DOWNLOAD_FORMAT_REQUIRED400NeinTask-Ergebnisrequest ohne erforderliche download-Abfrage
INVALID_DOWNLOAD_FORMAT400Neindownload muss xml oder pdf sein
AUTH_SERVICE_UNAVAILABLE503JaAuth-Backend nicht verfügbar
RATE_LIMIT_SERVICE_UNAVAILABLE503JaDer Rate-Limit-Dienst war nicht erreichbar; mit Backoff erneut versuchen
PLAN_TIER_CHECK_FAILED503JaPlan oder API-Zugang konnten nicht geprüft werden; mit Backoff erneut versuchen
API_CREDIT_SERVICE_UNAVAILABLE503JaDie Prüfung von Prepaid-API-Credits oder Kanalkontingent ist bei Konvertierungsuploads vorübergehend nicht verfügbar
RATE_LIMITED429JaRetry-After beachten. Retry-After, X-RateLimit-Limit-Minute und X-RateLimit-Limit-Hour werden nur bei 429-Antworten zurückgegeben; der Body enthält details.minute_count, details.hour_count, details.limit_minute und details.limit_hour
BAD_REQUEST400NeinUngültiges JSON oder ungültiger UUID-Pfadparameter
INVALID_QUERY_PARAMETER400Neininclude_validation_report_html muss true oder false sein
PAYLOAD_TOO_LARGE413NeinUpload-Größenlimit überschritten
INVALID_UPLOAD400NeinUpload konnte nicht gelesen/geparst werden
UPLOAD_FAILED422NeinEin optionales Kontextfeld (jurisdiction, transaction_scope, delivery_channel) enthielt einen unbekannten Wert; die erlaubten Werte stehen in der message
INVALID_PROFILE422NeinUnbekannter Profilname; details.allowed_profiles enthält die zulässigen Werte
TASK_NOT_READY202JaFür asynchrone Fertigstellung erneut pollen
TASK_NOT_FOUND404NeinDer Task ist unbekannt, gehört nicht zum Tenant oder ist nach Erreichen eines Endstatus über seine 24-Stunden-Aufbewahrung hinaus
VALIDATION_FAILED422NeinBlockierende Validierungsfehler bestehen weiterhin, einschließlich strikter ZUGFeRD-Voraussetzungsfehler und ungelöster blocking_source_conflict-Einträge; Rechnungsdaten vor erneutem Versuch korrigieren
AUTHORITATIVE_VALIDATION_UNAVAILABLE503JaAutoritative Validierung, Nachweisspeicherung oder Hybrid-Erzeugungsabhängigkeit nicht verfügbar; später erneut versuchen
TASK_STATUS_FAILED4xx/5xxBedingtRetry bei transientem Service-Zustand
TASK_RESULT_FAILED4xx/5xxBedingtRetry bei transientem Service-Zustand
TASK_FAILED500BedingtKonvertierungsfehler am Ergebnis-Endpunkt. Lesen Sie details.code und details.retryable: MULTIPLE_INVOICES_IN_DOCUMENT, NO_INVOICE_DETECTED, INSUFFICIENT_INVOICE_SIGNAL, SCHEMA_PARSE_FAILED und ARTIFACT_PARITY_FAILED sind endgültig; PROVIDER_ERROR und jeder unbekannte details.code richten sich nach details.retryable, und details.retryable=true bedeutet eine NEUE Konvertierung mit neuem Idempotency-Key statt eines erneuten Pollings desselben Tasks. Die fehlgeschlagene Konvertierung verbraucht keine Abrechnungseinheit
MULTIPLE_INVOICES_IN_DOCUMENT500 (details code)NeinEndgültig: Die Quelle enthält mehrere Rechnungen. In eine Datei pro Rechnung teilen und getrennte Konvertierungen starten
NO_INVOICE_DETECTED500 (details code)NeinEndgültig: Das Dokument scheint keine Rechnung zu sein; manuell bearbeiten
INSUFFICIENT_INVOICE_SIGNAL500 (details code)NeinEndgültig: Die Quelle enthält zu wenig Rechnungsdaten; bessere Quelle senden oder strukturierte Konvertierung nutzen
SCHEMA_PARSE_FAILED500 (details code)NeinFür diese Eingabe endgültig: Extrahierte Daten konnten nicht in das Schema eingelesen werden. Neue Konvertierung starten; bei Wiederholung mit demselben Dokument eskalieren
PROVIDER_ERROR500 (details code)BedingtExtraktionsanbieter fehlgeschlagen. details.retryable beachten; bei provider_context_too_large ein kleineres Quelldokument nutzen
XML_GENERATION_FAILED500JaTemporärer Fehler bei der XML-Generierung oder Timeout
PDF_GENERATION_FAILED500JaTemporärer Fehler bei der PDF-Generierung oder Timeout
ARTIFACT_GENERATION_RERUN_REQUIRED503NeinStrikte Artefakt-Erzeugung ist nach serverseitigen Retries fehlgeschlagen; nach Erholung der Abhängigkeit eine neue Konvertierung starten
EXTRACTION_INCOMPLETE_GROUP_FAILURE503NeinMindestens eine Extraktionsgruppe ist fehlgeschlagen. Der Task kann sich nicht erholen; neue Konvertierung starten und details.failed_groups prüfen
ARTIFACT_GENERATION_FAILED503 (details code)NeinWird bei fehlgeschlagenen Tasks für wiederholbare strikte Ausstellungsfehler hinterlegt; Ergebnis-Downloads liefern 503 ARTIFACT_GENERATION_RERUN_REQUIRED mit diesem Code in details
ARTIFACT_PARITY_FAILED500 (details code)NeinErscheint in den details von 500 TASK_FAILED, wenn das strikte Artefakt nicht den final geprüften Rechnungsdaten entspricht; mit der Korrelations-ID an den Support eskalieren
INTERNAL_ARTIFACT_INVARIANT_FAILED500NeinAbgeschlossener strikter Task hat kein sicheres gespeichertes Artefakt für den angeforderten Download; mit der Korrelations-ID an den Support eskalieren
PROFILE_MISMATCH422NeinDas angeforderte Profil passt beim Ergebnis-Download nicht zur CustomizationID des gespeicherten Ergebnisses
ZUGFERD_SOURCE_PDF_INCOMPATIBLE422NeinStrikte Hybrid-PDF-Erzeugung kann XML nicht in das hochgeladene Quell-PDF einbetten
ZUGFERD_SOURCE_PDF_REQUIRED422Neindownload=pdf für ZUGFERD erfordert einen PDF-Quellupload (DOCX/TXT-Quellen können das Hybrid-PDF nicht tragen); stattdessen download=xml anfragen
VALIDATION_REPORT_NOT_FOUND404NeinKein Validierungsbericht ist an den aktuellen Artefaktnachweis gebunden
VALIDATION_REPORT_FAILED4xx/5xxBedingtAbruf des Validierungsberichts fehlgeschlagen; Retry nur bei transienten 5xx-Fällen
OUTPUT_PROFILE_REQUIRED422NeinEin generischer Ausgabe-Contract erfordert ein explizites Profil, wenn kein eindeutiger Standard bestimmt werden kann
OUTPUT_PROFILE_CONFLICT422NeinProfil widerspricht dem gewählten Ausgabeformat oder der expliziten Variante
PROXY_ERROR502/504JaTransportfehler statt Konvertierungsergebnis (504 bei Zeitüberschreitung). Mit Backoff und demselben Idempotency-Key erneut versuchen

Häufige Fehler und nächste Schritte

  • Mit Backoff erneut versuchen: 429, 502, 504, 503 mit wiederholbarem Code sowie transiente 500-Fehler, die nicht TASK_FAILED oder INTERNAL_ARTIFACT_INVARIANT_FAILED sind. 500 TASK_FAILED ist nur wiederholbar, wenn details.retryable true ist, und dann nur als neue Konvertierung.
  • Nicht wiederholen: 400, 401, 402, 403, 404, 405, 413, 422, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_REPLAY_EXPIRED, 500 TASK_FAILED, wenn details.retryable nicht true ist, und 500 INTERNAL_ARTIFACT_INVARIANT_FAILED.
  • Request oder Quelldaten korrigieren: 400, 413, 422.
  • Zugang oder Zugangsdaten korrigieren: 401 INVALID_API_KEY. 403 API_NOT_ENABLED_FOR_TENANT bedeutet, dass der Schlüssel gültig ist, der External-API-Zugang für den Account aber nicht freigeschaltet ist — wenden Sie sich an den Support.
  • Enthaltenes Monatskontingent prüfen oder ein Prepaid-API-Credit-Paket kaufen: 402 INSUFFICIENT_API_CREDITS. Lesen Sie die jeweils vorhandenen details-Schlüssel (remaining bei Prepaid-Accounts oder included_remaining/credit_remaining/shortfall, wenn ein enthaltenes Kontingent greift).
  • Später weiter pollen: 202 TASK_NOT_READY.
  • Bei 500 TASK_FAILED details.code und details.retryable auswerten. MULTIPLE_INVOICES_IN_DOCUMENT, NO_INVOICE_DETECTED, INSUFFICIENT_INVOICE_SIGNAL, SCHEMA_PARSE_FAILED und ARTIFACT_PARITY_FAILED sind endgültig; PROVIDER_ERROR und jeder unbekannte Code richten sich nach details.retryable, und true bedeutet eine NEUE Konvertierung statt eines erneuten Pollings desselben Tasks. Eine fehlgeschlagene Konvertierung verbraucht keine Abrechnungseinheit.
  • Bei 422 VALIDATION_FAILED das betroffene Feld, die Regel-ID und den Behebungsvorschlag (Remediation) einem menschlichen Prüfer vorlegen, bevor mit korrigierten Rechnungsdaten erneut versucht wird.
  • Bei 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE denselben Task später erneut abrufen; es wurde kein ungeprüftes Artefakt ausgeliefert. Bei 503 ARTIFACT_GENERATION_RERUN_REQUIRED und 503 EXTRACTION_INCOMPLETE_GROUP_FAILURE stattdessen eine neue Konvertierung starten.
  • 502 und 504 PROXY_ERROR sind Transportfehler und keine Konvertierungsergebnisse; mit Backoff und demselben Idempotency-Key erneut versuchen.

Rate- und Payload-Limits

Rate-Limits pro API-Schlüssel und Payload-Größen gelten für alle API-Aufrufe. Abgelehnte Konvertierungen verbrauchen keine Prepaid-API-Credits; Rate-Limits werden separat pro Endpunkt ermittelt.

  • Endpunktbezogene Limits sind kostenbewertet, und jeder Endpunkt hat einen eigenen Bucket, damit Polling den Konvertierungsdurchsatz nicht aushungert. Standardwerte pro API-Schlüssel: POST /invoices:convert und POST /invoices:convert-structured 30/min und 500/hour; GET /tasks/{task_id} 10/min und 120/hour; GET /tasks/{task_id}/result 10/min und etwa 134/hour; GET /tasks/{task_id}/validation-report 10/min und 120/hour.
  • Kontingent-Header werden nur bei 429 RATE_LIMITED-Antworten zurückgegeben. Erfolgreiche Antworten enthalten keine Kontingent-Header; behandeln Sie deshalb die obige Tabelle als geltenden Vertrag und lesen Sie die exakten effektiven Werte aus einer 429-Antwort.
  • Der Status-Bucket ist die bindende Grenze für das Polling: Warten Sie nach dem angenommenen 202 etwa 20 Sekunden bis zum ersten Statusaufruf, erhöhen Sie danach die Abstände (20s, 30s, 45s, 60s und ab dann 60s) und beenden Sie das Polling bei completed oder failed. Pollen Sie nicht alle 10 Sekunden; ein einzelner so abgefragter Task verbraucht sein gesamtes Stundenkontingent in 20 Minuten.
  • Maximale Größe für Quelldokumente: 20 MB für PDF-, DOCX- oder TXT-Dateien.
  • Maximale Uploadgröße strukturierter Daten: 2 MB insgesamt über alle data_file-Parts.
  • Maximale JSON-Payloadgröße: 1 MB
  • 429-Antworten enthalten Retry-After, X-RateLimit-Limit-Minute und X-RateLimit-Limit-Hour sowie details.minute_count, details.hour_count, details.limit_minute und details.limit_hour.

Retry-Leitfaden

  • Verwenden Sie exponentielles Backoff mit Jitter und denselben Idempotency-Key bei jedem Retry eines Schreib-Requests.
  • Entscheiden Sie anhand des maschinenlesbaren code — und bei 500 TASK_FAILED anhand von details.code plus details.retryable — nie allein anhand des HTTP-Status. Ein 500 ist in dieser API nicht automatisch wiederholbar.
  • Wiederholbar: 429, 502, 504, 503 mit wiederholbarem Code, transiente 500-Fehler, die NICHT TASK_FAILED oder INTERNAL_ARTIFACT_INVARIANT_FAILED sind, sowie 500 TASK_FAILED, wenn details.retryable true ist (transiente Provider-Fehler: Rate-Limit, Timeout, Transportfehler) — dieser Fall wird als NEUE Konvertierung mit neuem Idempotency-Key wiederholt, nicht durch erneutes Polling desselben Tasks.
  • Nie wiederholen: 400, 401, 402, 403, 404, 405, 413, 422, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_REPLAY_EXPIRED, 500 TASK_FAILED, wenn details.retryable nicht true ist, und 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. Eine endgültig fehlgeschlagene Konvertierung verbraucht keine Abrechnungseinheit.
  • 409 IDEMPOTENCY_IN_PROGRESS ist mit DEMSELBEN Key nach kurzer Wartezeit wiederholbar; ein hängender In-Progress-Anspruch wird nach 15 Minuten freigegeben.
  • 503 ARTIFACT_GENERATION_RERUN_REQUIRED und 503 EXTRACTION_INCOMPLETE_GROUP_FAILURE erfordern eine NEUE Konvertierung statt eines Retrys desselben Tasks.

Task-Lebenszyklus und Aufbewahrung

  • Ein Task und seine gespeicherten Artefakte werden 24 Stunden nach Erreichen eines Endstatus (completed oder failed) aufbewahrt und danach gelöscht. Nach der Löschung liefern Status-, Ergebnis- und Validierungsbericht-Anfragen 404 TASK_NOT_FOUND.
  • Es gibt kein festes Konvertierungs-Timeout. Ein Task schlägt fehl, wenn 5 Minuten lang kein Stufen- oder Fortschrittsupdate erfolgt (Stillstandsfenster) oder wenn die gesamte Verarbeitung die absolute Obergrenze von 15 Minuten überschreitet.
  • Setzen Sie Ihr clientseitiges Timeout auf etwa 16 Minuten ab dem angenommenen 202. Die meisten Konvertierungen sind deutlich unter zwei Minuten fertig.
  • Idempotenz-Datensätze bestehen 24 Stunden und entsprechen damit der Task-Aufbewahrung. Ein hängender Request wird nach 15 Minuten freigegeben.
  • Rate-Limit-Zähler werden in einem rollierenden Fenster zurückgesetzt.

Supportmodell

  • Support zu Geschäftszeiten mit wirtschaftlich angemessenen Bemühungen.
  • Kein formales SLA, keine Service Credits und keine Antwortzeitverpflichtung, sofern nicht in einem Order Form vereinbart.

Änderungsprotokoll

Neueste extern sichtbare API-Änderungen.

2026-09-08

seller_master_data behandelt electronic_address und electronic_address_scheme jetzt als ein optionales Feldpaar. Senden Sie beide Felder oder lassen Sie beide weg; ein unvollständiges Paar liefert 400 INVALID_SELLER_MASTER_DATA.

2026-09-07

Korrektur der Preisdokumentation: 1.000 Prepaid-Credits kosten 400 EUR (0,40 EUR je Credit). Die Pakete mit 100, 200 und 500 Credits kosten weiterhin 50, 100 und 250 EUR. Die tatsächlich berechneten Preise und bestehende Käufe bleiben unverändert.

2026-08-24

Die Dokumentkonvertierung ignoriert eingebettete Rechnungs-XML jetzt standardmäßig. Setzen Sie use_embedded_xml=true nur, wenn die Integration die eingebettete XML ausdrücklich als primäre Extraktionsquelle akzeptiert. Der E-Mail-Import ignoriert eingebettete Rechnungs-XML immer. Eine Änderung von use_embedded_xml ändert den Idempotenz-Hash des Requests; verwenden Sie bei einer Änderung dieser Option einen neuen Idempotency-Key.

2026-08-20

Wenn Verkäufer-Stammdaten ein Feld füllen, bleiben übrige Extraktions-Flags dazu sichtbar, blockieren aber nicht mehr den strengen E-Mail-Import oder die External API. Käufer, Positionen, Steuer, Lieferung, Fälligkeit, Skonto, Verwendungszweck, ungefüllte Profilfelder und ungültige Profilwerte bleiben blockierend.

2026-08-07

Enterprise wurde per Direktkauf für 50 EUR/Monat oder 420 EUR/Jahr verfügbar. Enterprise enthält 100 gemeinsame E-Mail/API-Konvertierungen pro Monat; weitere Konvertierungen nutzen Prepaid-Credits zu je 0,40–0,50 EUR. API-Schlüssel brauchen keine manuelle Freigabe mehr.

2026-07-29

Aktuellen Fehlerkatalog und code-spezifische Retry-Regeln veröffentlicht. Ein 500-Status ist nicht automatisch wiederholbar; code, details.code und details.retryable prüfen. Beide details-Formen für 402 INSUFFICIENT_API_CREDITS und die unterschiedlichen 409-Idempotenzpfade dokumentiert. Nachweis-Header des Validierungsberichts, 24-Stunden-Aufbewahrung, Task-Timeouts und endpunktspezifische Rate-Limits veröffentlicht. Geschlossene Format/Profil-Tabelle veröffentlicht und Hinweise zu Download, METHOD_NOT_ALLOWED und PROFILE_MISMATCH korrigiert.

2026-07-28

API-Konvertierung lehnt eine bestätigte Quelle mit mehreren Rechnungen jetzt endgültig mit MULTIPLE_INVOICES_IN_DOCUMENT ab. Bestätigte Mehrfachrechnungen aufteilen. Ein unsicheres Signal liefert stattdessen 422 VALIDATION_FAILED zur Prüfung.

2026-07-26

Aktivierte Verkäufer-Stammdaten ersetzen jetzt passende extrahierte Verkäufer- oder Zahlungswerte. Fehlende Profilfelder lassen extrahierte Werte unverändert; Abweichungen bleiben nicht blockierende Prüfwarnungen.

2026-07-25

Durch 2026-07-26 ersetzt: Verkäufer-Stammdaten ersetzen jetzt passende extrahierte Werte, statt nur fehlende Werte zu ergänzen.

2026-07-10

Dokumentations-Backfill; keine Änderung des Laufzeitverhaltens. Der Fehlerkatalog dokumentiert jetzt zuvor nicht dokumentierte Laufzeit-Fehlercodes, darunter API_CREDIT_SERVICE_UNAVAILABLE, TASK_NOT_FOUND, INVALID_CLIENT_METADATA, INVALID_SELLER_MASTER_DATA, PROFILE_MISMATCH, ZUGFERD_SOURCE_PDF_REQUIRED, VALIDATION_REPORT_NOT_FOUND, VALIDATION_REPORT_FAILED, INVALID_QUERY_PARAMETER und METHOD_NOT_ALLOWED. Clients, die Fehlerantworten über das maschinenlesbare code-Feld auswerten, benötigen keine Änderungen; Clients mit fester Codeliste sollten die neu dokumentierten Werte ergänzen. Changelog-Daten korrigiert: Die Unterstützung für DOCX/TXT-Quellen erschien am 2026-06-30, nicht am 2026-07-06.

2026-07-06

Payloads abgeschlossener Tasks können zusätzliche _processing_warnings- und _validation_warnings-Einträge mit SOURCE_CONTEXT_*-Regel-IDs enthalten, wenn Quellenbelege vor der Extraktion fehlten, zweifelhaft oder abgeschnitten waren. Behandeln Sie SOURCE_CONTEXT_*-Einträge als Prüfsignale für kundenseitige Ausnahmebehandlung; strikte Artefakt-Downloads bleiben durch Validierungsnachweis und Artefaktprüfungen abgesichert.

2026-07-03

Strikte ZUGFeRD-Voraussetzungsfehler (fehlende Pflichtfelder für die Hybrid-Erzeugung) schlagen jetzt als 422 VALIDATION_FAILED mit den blockierenden Regel-IDs fehl statt als wiederholbares 503; leiten Sie diese in einen Datenkorrektur-Ablauf, nicht in eine Retry-Schleife. Für XML-only-Formate (XRECHNUNG, EN16931, UBL, CII) ist die PDF-Darstellung jetzt ein Best-Effort-Komfortartefakt: download=xml bleibt bei abgeschlossenen Tasks maßgeblich und verfügbar, während download=pdf nicht verfügbar sein kann, wenn die Darstellung nach der XML-Ausstellung fehlschlug. Konvertierungen mit ungelösten blockierenden Quellkonflikten schlagen jetzt als 422 VALIDATION_FAILED mit blocking_source_conflict-Einträgen fehl, statt ein Artefakt auszustellen.

2026-06-30

POST /api/v1/invoices:convert akzeptiert im file-Feld jetzt PDF-, DOCX- und TXT-Rechnungsquelldokumente. Alte DOC-, RTF-, Bild- und andere nicht unterstützte Quelldateien werden vor Start der Konvertierung abgelehnt. ZUGFeRD/Factur-X-Hybrid-PDF-Downloads erfordern weiterhin einen PDF-Quellupload; für DOCX/TXT-Quellkonvertierungen XML-Downloads verwenden. Optionales include_validation_report_html=true auf GET /api/v1/tasks/{task_id} ergänzt, um den bereinigten HTML-Validierungsbericht bei Verfügbarkeit inline zu liefern. Konvertierungsuploads akzeptieren jetzt an beiden Endpunkten optionale use_seller_master_data- und seller_master_data-Felder, damit freigegebene Tenants gespeicherte oder request-bezogene Verkäufer-Stammdaten aktivieren können.

2026-06-29

GET /api/v1/tasks/{task_id}/validation-report?download=html|xml ergänzt, um den Validierungsbericht zum aktuellen strikten Ergebnisartefakt-Nachweis abzurufen. Antworten des Validierungsberichts enthalten Task-ID, Artefakt-SHA-256, Validierungsnachweis-ID, Berichtsnachweis-ID, Berichts-Content-Type und Korrelations-ID-Header.

2026-06-10

Gesendete Rechnungsdaten sind jetzt die Datenquelle für hybride ZUGFeRD-Ausgaben; deterministische Bereinigung und Steuernormalisierung bleiben aktiv. Tasks schlagen bei ausbleibendem Fortschritt oder am 15-Minuten-Maximum fehl, nicht nach einem festen Fünf-Minuten-Timeout.

2026-06-09

Fehler beim Speichern der Nutzungsdaten blockieren keine fertige validierte Antwort und berechnen keinen zusätzlichen Credit; fehlgeschlagene Ereignisse werden abgeglichen.

2026-06-02

External API-Zugang ist jetzt als freigabepflichtiger Zugang dokumentiert, nicht als unbeschränkte Key-Erstellung. Klargestellt, dass kein formales SLA, keine Service Credits und keine Vertragsstrafen gelten, sofern nicht in einem Order Form vereinbart. format ist jetzt an beiden Konvertierungsendpunkten erforderlich; fehlende Werte liefern 400 FORMAT_REQUIRED und nicht unterstützte Werte 422 INVALID_FORMAT. download ist jetzt bei Task-Ergebnisrequests erforderlich; fehlende Werte liefern 400 DOWNLOAD_FORMAT_REQUIRED und nicht unterstützte Werte 400 INVALID_DOWNLOAD_FORMAT. Konvertierungsuploads akzeptieren jetzt client_reference/external_invoice_id und source_system für kundenseitigen Abgleich. Angenommene Konvertierungen und Task-Statusantworten enthalten jetzt status_url, primary_result_format, primary_result_url sowie gesendete Abgleichsfelder.

2026-06-01

Strukturierte Konvertierung akzeptiert jetzt alle öffentlichen Ausgabeformate: XRECHNUNG, ZUGFeRD, EN16931, UBL und CII. Strukturierte Konvertierung akzeptiert jetzt wiederholbare data_file-Teile sowie die Aliase data_files und data_files[] für getrennte ERP-Exporte. Strukturierte Multi-Datei-Bundles müssen genau eine Rechnung beschreiben und schlagen bei widersprüchlichen oder fehlenden Bundle-Rechnungs-IDs früh fehl. Klargestellt, dass mehrere Rechnungsdokumente als separate Konvertierungs-Tasks mit jeweils eigenem Idempotency-Key eingereicht werden sollten.

2026-05-27

POST /api/v1/invoices:convert-structured für Träger-PDF plus CSV/JSON/XML/XLSX/TXT-Konvertierung aus strukturierten Daten über unterstützte Ausgabeformate ergänzt. Dokumentiert, dass strukturierte Daten an diesem Endpunkt die einzige semantische Quelle sind; das PDF wird für die Hybrid-Einbettung verwendet. OpenAPI- und Postman-Artefakte für strukturierte Konvertierung aktualisiert.

2026-05-26

Strikte XML- und Hybrid-PDF-Artefakte erhielten interne Paritätsdaten; result_artifacts zeigt Bereitschaft und Validierungsstatus. Die dokumentierte Produktions-Basis-URL wurde auf https://www.invoice-converter.com/api/v1 geändert.

2026-05-19

GET /api/v1/tasks/{task_id}/result dient nur noch zum Abruf; der Aufruf erzeugt, repariert oder validiert keine Dateien. Strikte Tasks enden erst nach Speicherung eines validierten Artefakts; ein fehlender aktueller Nachweis führt zum geschlossenen Fehler. External-API-Konvertierung ist fest auf strikte Ausgabe eingestellt, ohne Entwurf oder Warnungsübersteuerung. Der Task-Status erhielt result_artifacts-Diagnosen und dokumentierte delivery_channel-Werte.

2026-05-08

Prepaid-API-Credits für Nicht-Enterprise-Mandanten ergänzt. 402 INSUFFICIENT_API_CREDITS für freigegebene Mandanten ohne Enterprise-Abrechnung per Order Form oder Prepaid-Credits dokumentiert. Bestätigt, dass idempotente Replays keine zusätzlichen API-Credits verbrauchen. Klargestellt, dass External API V1 das Modellrouting serverseitig steuert, während Profil- und Lieferkontext vom Aufrufer gesetzt werden.

2026-03-28

Der Task-Status erhielt Bereitschaftsdiagnosen für XML/PDF-Artefakte. Strikte Ergebnisdownloads liefern Dateien erst nach serverseitigen Artefaktprüfungen.

2026-03-26

Erfolgreiche Ergebnisdownloads erhielten einen serverseitigen Validierungsnachweis für das zurückgegebene Artefakt. Fehlende Validierungs- oder Nachweisabhängigkeiten liefern 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE. Zwischengespeicherte Downloads werden nur mit weiterhin aktuellem gespeichertem Validierungsnachweis wiederverwendet.

2026-03-06

Task-result-Downloads für CII- und ZUGFERD-Ausgaben formatgetreu gemacht. Wiederverwendung zwischengespeicherter Ergebnisartefakte für wiederholte XML-/PDF-Downloads desselben Tasks ergänzt. Polling-Kontingente an endpoint-bezogene gewichtete Rate-Limit-Buckets angeglichen.

2026-02-23

Klarere und konsistente API-Fehlerantworten über alle Endpunkte ergänzt. Convert-Optionen erweitert und XML-/PDF-Downloadverhalten für Task-Ergebnisse dokumentiert. Retry-Sicherheit mit strengeren Idempotenzanforderungen und Validierung verbessert. OpenAPI-/Postman-Artefakte an das aktuelle API-Verhalten angepasst.

Lieferartefakte

Laden Sie maschinenlesbare Integrationsartefakte für die Developer API herunter.

Postman und OpenAPI verwenden

  • Postman-Collection importieren und die Collection-Variablen base_url, api_key und idempotency_key setzen.
  • Collection der Reihe nach ausführen: convert, Status pollen, dann Ergebnis abrufen.
  • OpenAPI JSON für typisierte Clients nutzen, aber Datei-Upload, Polling und binäre Results mit Integrationstests absichern.
  • X-Correlation-ID in Logs speichern, damit Support Requests Ende-zu-Ende nachverfolgen kann.

Technisches Feedback senden

Teilen Sie Implementierungsfragen, Risiken und erforderliche Vertragsänderungen mit unserem Team.