# 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,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-08-07. ## Wichtige Funktionen - Upload-Endpunkte für PDF-Rechnungen und strukturierte Rechnungsdaten - KI-gestützte Extraktion von Rechnungsdaten - 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 für 50 €/Monat oder 420 €/Jahr auf der Preisseite. 2. Nutzen Sie die 100 monatlich enthaltenen gemeinsamen E-Mail/API-Konvertierungen; weitere Konvertierungen kosten über Prepaid-Credits je 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. ## Enterprise starten - [Enterprise-Tarif und Preise](/pricing) ## 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` 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_XRECHNUNG]` (Standard `EN16931`) und `ZUGFERD` akzeptiert `[ZUGFERD_EN16931, 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 ## 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,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. 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_XRECHNUNG] (Standard EN16931); ZUGFERD → [ZUGFERD_EN16931, 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; 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. 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_XRECHNUNG] (Standard EN16931); ZUGFERD → [ZUGFERD_EN16931, 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. 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":""}); 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) Download the validation report tied to the current validated result artifact. The report is available only after strict conversion has produced a cached artifact with current validation proof, and returns 404 when no report is bound to the delivered artifact. A 202 carries the standard TASK_NOT_READY error envelope, not a file body. Successful responses carry 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, X-Validator-Bundle-Id, plus X-Task-Id, X-Validation-Report-Proof-Id, X-Validation-Report-Content-Type, X-Validation-Report-Format, X-Validation-Report-Source, and X-Report-Source-Artifact-Format. Those artifact-level diagnostics describe the validated result artifact the report covers, not the returned report bytes: X-Artifact-Sha256 is the SHA-256 of that source artifact and must not be used to checksum the downloaded report, while X-Validation-Report-Proof-Id identifies the proof that supplied the report payload. Rate limit 10/min and 120/hour. Anfrage: none (GET); task_id (path, required) — UUID returned by the convert endpoint; download (query, optional) — html or xml. Antwort: 200 OK. ## Ausgabeformat-Matrix | Format | Syntax | Version / Profil | Content-Type | Dateiendung | | --- | --- | --- | --- | --- | | XRECHNUNG | UBL 2.1 XML | XRechnung 3.0.2 | application/xml | .xml | | ZUGFERD | CII-XML (download=xml) / hybrides PDF/A-3 (download=pdf) | ZUGFeRD 2.3.2 / Factur-X 1.07.2 | application/xml oder application/pdf | .xml / .pdf | | EN16931 | UBL 2.1 XML | EN 16931 | application/xml | .xml | | UBL | UBL 2.1 XML | OASIS UBL 2.1 | application/xml | .xml | | CII | UN/CEFACT CII XML | D16B | application/xml | .xml | ## Fehlervertrag | Code | HTTP | Wiederholbar | Hinweise | | --- | --- | --- | --- | | AUTHENTICATION_REQUIRED | 401 | Nein | Fehlender/leerer Bearer-Token | | INVALID_API_KEY | 401 | Nein | API-Schlüssel nicht gefunden, widerrufen oder abgelaufen | | API_NOT_ENABLED_FOR_TENANT | 403 | Nein | Key is valid but External API access is not enabled for the account; contact support instead of retrying | | INSUFFICIENT_API_CREDITS | 402 | Nein | Enthaltenes 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_REQUIRED | 400 | Nein | Schreibendpunkt ohne Idempotency-Key aufgerufen | | INVALID_IDEMPOTENCY_KEY | 400 | Nein | Idempotency-Key muss [A-Za-z0-9._:-]+ entsprechen und darf höchstens 200 Zeichen lang sein | | IDEMPOTENCY_CONFLICT | 409 | Nein | Der 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_PROGRESS | 409 | Ja | Der 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_EXPIRED | 409 | Nein | The original task is past its 24-hour retention and cannot be recovered; start a new conversion with a new key | | FORMAT_REQUIRED | 400 | Nein | Konvertierungsrequest ohne erforderliches format | | INVALID_FORMAT | 422 | Nein | Nicht unterstütztes Konvertierungsformat | | CLIENT_REFERENCE_CONFLICT | 400 | Nein | client_reference und external_invoice_id unterscheiden sich | | INVALID_CLIENT_METADATA | 400 | Nein | client_reference, external_invoice_id oder source_system überschreitet das Längenlimit oder enthält Steuerzeichen | | INVALID_SELLER_MASTER_DATA | 400 | Nein | use_seller_master_data oder seller_master_data ist nicht parsebar oder besteht die Feldvalidierung nicht | | METHOD_NOT_ALLOWED | 405 | Nein | Konvertierungspfade akzeptieren nur POST und Task-Pfade nur GET; die Antwort enthält Allow: POST, OPTIONS (Konvertierung) bzw. Allow: GET, OPTIONS (Task) | | DOWNLOAD_FORMAT_REQUIRED | 400 | Nein | Task-Ergebnisrequest ohne erforderliche download-Abfrage | | INVALID_DOWNLOAD_FORMAT | 400 | Nein | download muss xml oder pdf sein | | AUTH_SERVICE_UNAVAILABLE | 503 | Ja | Auth-Backend nicht verfügbar | | RATE_LIMIT_SERVICE_UNAVAILABLE | 503 | Ja | Der Rate-Limit-Dienst war nicht erreichbar; mit Backoff erneut versuchen | | PLAN_TIER_CHECK_FAILED | 503 | Ja | Plan/API access could not be verified right now; retry with backoff | | API_CREDIT_SERVICE_UNAVAILABLE | 503 | Ja | Die Prüfung von Prepaid-API-Credits oder Kanalkontingent ist bei Konvertierungsuploads vorübergehend nicht verfügbar | | RATE_LIMITED | 429 | Ja | Retry-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_REQUEST | 400 | Nein | Ungültiges JSON oder ungültiger UUID-Pfadparameter | | INVALID_QUERY_PARAMETER | 400 | Nein | include_validation_report_html muss true oder false sein | | PAYLOAD_TOO_LARGE | 413 | Nein | Upload-Größenlimit überschritten | | INVALID_UPLOAD | 400 | Nein | Upload konnte nicht gelesen/geparst werden | | UPLOAD_FAILED | 422 | Nein | Ein optionales Kontextfeld (jurisdiction, transaction_scope, delivery_channel) enthielt einen unbekannten Wert; die erlaubten Werte stehen in der message | | INVALID_PROFILE | 422 | Nein | The value is not a recognized profile name; details.allowed_profiles lists the accepted set | | TASK_NOT_READY | 202 | Ja | Für asynchrone Fertigstellung erneut pollen | | TASK_NOT_FOUND | 404 | Nein | Der Task ist unbekannt, gehört nicht zum Tenant oder ist nach Erreichen eines Endstatus über seine 24-Stunden-Aufbewahrung hinaus | | VALIDATION_FAILED | 422 | Nein | Blockierende Validierungsfehler bestehen weiterhin, einschließlich strikter ZUGFeRD-Voraussetzungsfehler und ungelöster blocking_source_conflict-Einträge; Rechnungsdaten vor erneutem Versuch korrigieren | | AUTHORITATIVE_VALIDATION_UNAVAILABLE | 503 | Ja | Autoritative Validierung, Nachweisspeicherung oder Hybrid-Erzeugungsabhängigkeit nicht verfügbar; später erneut versuchen | | TASK_STATUS_FAILED | 4xx/5xx | Bedingt | Retry bei transientem Service-Zustand | | TASK_RESULT_FAILED | 4xx/5xx | Bedingt | Retry bei transientem Service-Zustand | | TASK_FAILED | 500 | Bedingt | Konvertierungsfehler 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_DOCUMENT | 500 (details code) | Nein | Terminal: the source document contains more than one invoice, corroborated by distinct invoice identifiers or a reported invoice count. details.retryable and details.can_review are false. Split the PDF into one file per invoice and start a separate conversion for each invoice | | NO_INVOICE_DETECTED | 500 (details code) | Nein | Terminal: the document does not look like an invoice. Route to human handling | | INSUFFICIENT_INVOICE_SIGNAL | 500 (details code) | Nein | Terminal: not enough invoice data for reliable extraction. Supply a better source document or use structured conversion | | SCHEMA_PARSE_FAILED | 500 (details code) | Nein | Terminal for that input: extraction returned a payload that failed schema parsing. Start a new conversion; escalate if it repeats on the same document | | PROVIDER_ERROR | 500 (details code) | Bedingt | Extraction-provider failure; details.retryable is authoritative. When details.classification is provider_context_too_large, use a smaller source document | | XML_GENERATION_FAILED | 500 | Ja | Temporärer Fehler bei der XML-Generierung oder Timeout | | PDF_GENERATION_FAILED | 500 | Ja | Temporärer Fehler bei der PDF-Generierung oder Timeout | | ARTIFACT_GENERATION_RERUN_REQUIRED | 503 | Nein | Strikte Artefakt-Erzeugung ist nach serverseitigen Retries fehlgeschlagen; nach Erholung der Abhängigkeit eine neue Konvertierung starten | | EXTRACTION_INCOMPLETE_GROUP_FAILURE | 503 | Nein | Extraction finished with one or more failed field groups. The same task will not recover: start a NEW conversion. details carries type "dependency", dependency "parallel_extraction", stage "extraction", retryable true, same_task_retryable false, recovery "start_new_conversion", and failed_groups | | ARTIFACT_GENERATION_FAILED | 503 (details code) | Nein | Wird bei fehlgeschlagenen Tasks für wiederholbare strikte Ausstellungsfehler hinterlegt; Ergebnis-Downloads liefern 503 ARTIFACT_GENERATION_RERUN_REQUIRED mit diesem Code in details | | ARTIFACT_PARITY_FAILED | 500 (details code) | Nein | Erscheint 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_FAILED | 500 | Nein | Abgeschlossener strikter Task hat kein sicheres gespeichertes Artefakt für den angeforderten Download; mit der Korrelations-ID an den Support eskalieren | | PROFILE_MISMATCH | 422 | Nein | Das angeforderte Profil passt beim Ergebnis-Download nicht zur CustomizationID des gespeicherten Ergebnisses | | ZUGFERD_SOURCE_PDF_INCOMPATIBLE | 422 | Nein | Strikte Hybrid-PDF-Erzeugung kann XML nicht in das hochgeladene Quell-PDF einbetten | | ZUGFERD_SOURCE_PDF_REQUIRED | 422 | Nein | download=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_FOUND | 404 | Nein | Kein Validierungsbericht ist an den aktuellen Artefaktnachweis gebunden | | VALIDATION_REPORT_FAILED | 4xx/5xx | Bedingt | Abruf des Validierungsberichts fehlgeschlagen; Retry nur bei transienten 5xx-Fällen | | OUTPUT_PROFILE_REQUIRED | 422 | Nein | Ein generischer Ausgabe-Contract erfordert ein explizites Profil, wenn kein eindeutiger Standard bestimmt werden kann | | OUTPUT_PROFILE_CONFLICT | 422 | Nein | Profil widerspricht dem gewählten Ausgabeformat oder der expliziten Variante | | PROXY_ERROR | 502/504 | Ja | Transportfehler 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-08-07 Documentation release 1.13.0: Enterprise is available through direct checkout for EUR 50 per month or EUR 420 per year. Every active Enterprise subscription includes 100 conversion units per month shared by Email Import and External API V1; additional units use prepaid credits at EUR 0.50 each. Email Import and External API V1 no longer require manual account approval. Email Import still requires profile enablement and a verified sender. ### 2026-07-29 Documentation release 1.12.0. No runtime behavior changed on this date; these entries document behavior that was already live. MULTIPLE_INVOICES_IN_DOCUMENT is now published in the error catalog. It is returned as 500 TASK_FAILED with details.code=MULTIPLE_INVOICES_IN_DOCUMENT, details.retryable=false, and details.can_review=false. It is terminal: split the source into one document per invoice. The failed attempt does not consume a billing unit. Retry guidance corrected: a 500 is not automatically retryable. Branch on code, and on details.code plus details.retryable for 500 TASK_FAILED, instead of on the HTTP status alone. Treat 500 TASK_FAILED as terminal unless details.retryable is true (transient provider failures such as rate limiting, timeouts, and transport errors), in which case start a new conversion with a new Idempotency-Key rather than re-polling the same task. Never retry 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. Billing is documented as included-allowance-then-credits, so 402 INSUFFICIENT_API_CREDITS has two details shapes: prepaid (remaining, minimum_purchase) and included allowance (included_remaining, credit_remaining, shortfall, minimum_purchase). Newly documented runtime error codes that were already being returned: 403 API_NOT_ENABLED_FOR_TENANT, 409 IDEMPOTENCY_IN_PROGRESS, 409 IDEMPOTENCY_REPLAY_EXPIRED, 422 INVALID_PROFILE, 422 UPLOAD_FAILED, 400 INVALID_IDEMPOTENCY_KEY, 503 PLAN_TIER_CHECK_FAILED, 503 RATE_LIMIT_SERVICE_UNAVAILABLE, and 503 EXTRACTION_INCOMPLETE_GROUP_FAILURE. The 409 class is split by retry semantics: IDEMPOTENCY_IN_PROGRESS is retryable with the same key after a short delay, while IDEMPOTENCY_CONFLICT and IDEMPOTENCY_REPLAY_EXPIRED require a new key. Validation-report header passthrough fixed, and X-Validation-Report-Format, X-Validation-Report-Source, and X-Report-Source-Artifact-Format are now published. On the validation-report endpoint, X-Artifact-Sha256 is the SHA-256 of the result artifact the report validates, not of the returned report bytes; X-Validation-Report-Proof-Id identifies the proof that supplied the report payload. Added retention and lifecycle statements: 24-hour task/artifact retention after a terminal state, 24-hour idempotency records, a 15-minute in-progress reclaim, a 5-minute stall window, a 15-minute hard cap, and a recommended ~16-minute client timeout. Rate limits and polling guidance replaced with per-endpoint numbers, including the previously missing validation-report bucket. Quota headers are returned on 429 responses only, and the former "poll every 10-15 seconds" advice is replaced with a first-poll delay plus backoff. Published a closed format x profile compatibility table with the default profile for each format, and corrected download=xml on a completed task from "always available" to expected-available. Corrected 405 METHOD_NOT_ALLOWED to return Allow: POST, OPTIONS on conversion paths and Allow: GET, OPTIONS on task paths, and corrected 422 PROFILE_MISMATCH: there is no profile query parameter, and the fix is to start a new conversion with an aligned profile. ### 2026-07-28 External API conversions now run the same document-scope gate as the interactive product, including on forced extraction modes that previously skipped it. A source document whose extraction reports multiple invoices, corroborated by two or more distinct invoice identifiers or by an invoice count with no identifiers, now fails terminally with MULTIPLE_INVOICES_IN_DOCUMENT. The failure is not retryable: split the source into one document per invoice and submit each separately. An uncorroborated multiple_invoices verdict no longer fails the conversion. On strict API issuance it returns 422 VALIDATION_FAILED with a blocking_source_conflict issue entry, which covers duplicate renditions such as an original plus its copy, a reprint, or a second-language rendition. ### 2026-07-26 When seller master data is enabled, every supplied profile value replaces the corresponding extracted seller or payment value. Fields absent from the profile remain unchanged. Source differences are non-blocking review warnings. ### 2026-07-25 Superseded by the 2026-07-26 entry above. Seller master data filled missing seller and payment fields only; explicit invoice values remained unchanged, and material profile/source conflicts blocked strict issuance until review. Since 2026-07-26 every supplied profile value replaces the corresponding extracted value instead. ### 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 Invoice data you submit is now the source of truth during hybrid ZUGFeRD generation; the server no longer overrides submitted quantities or totals with values recovered from the uploaded PDF. Deterministic cleanup and tax normalization still apply. Long-running conversions are no longer failed at a fixed 5-minute processing timeout. Tasks now fail only when they stop making progress for the stall window or exceed the absolute 15-minute hard cap, and extraction retries are bounded by a total wall-clock budget. ### 2026-06-09 Clarified that usage-tracking persistence failures are fail-open for response delivery: ready validated artifact responses are not denied, no extra prepaid API credit is consumed, and failed usage events are queued internally for reconciliation. ### 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 Strict XML and hybrid ZUGFeRD PDF result artifacts now carry internal artifact parity metadata; public clients should use task-status result_artifacts for artifact readiness and validation-state diagnostics. Updated the documented production base URL to https://www.invoice-converter.com/api/v1. ### 2026-05-19 Task-result downloads are now strict retrieval-only: no XML/PDF generation, AI call, repair, or validation runs on GET /api/v1/tasks/{task_id}/result. Strict tasks complete only after a validated artifact is stored; completed tasks without a current proof fail closed with 500 INTERNAL_ARTIFACT_INVARIANT_FAILED. External API conversions are permanently pinned to strict issuance: no draft output, no warning override, and artifact validation always required. Conversions run on a dedicated processing tier chosen by the service. Added additive result_artifacts diagnostics to the task status response, and documented the canonical delivery_channel values PEPPOL, DIRECT_XML, PORTAL, EMAIL_PDF, and UNKNOWN. Documented 422 ZUGFERD_SOURCE_PDF_INCOMPATIBLE, and clarified that missing XRechnung/Peppol target metadata such as BT-10, BT-49, and BG-16 is a validation correction flow rather than a transport retry. ### 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 Task status responses expose artifact readiness diagnostics for XML/PDF result availability. Documented that strict result downloads only return files after server-side artifact gates pass. ### 2026-03-26 Successful task-result downloads are backed by a server-side validation proof for the returned bytes. The result endpoint returns 503 AUTHORITATIVE_VALIDATION_UNAVAILABLE when required authoritative validation, proof persistence, or hybrid-generation dependencies are unavailable. Cached task-result downloads are reused only when the cached artifact still has a persisted validation proof. ### 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. - [OpenAPI JSON](/developer-api/v1/openapi.json) - [Postman-Kollektion](/developer-api/v1/postman.json) ## 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. - [Technisches Feedback per E-Mail senden](mailto:contact@invoice-converter.com?subject=Technisches%20Review-Feedback%20zur%20Externen%20API%20V1&body=Hallo%20Invoice-Converter-Team%2C%0D%0A%0D%0AWir%20haben%20die%20Externe-API-V1-Dokumentation%20gepr%C3%BCft%20und%20haben%20folgendes%20Feedback%3A%0D%0A%0D%0A1)%20%0D%0A2)%20%0D%0A3)%20%0D%0A%0D%0AViele%20Gr%C3%BC%C3%9Fe%2C)