# Externe API V1 Dokumentation Technisches Dokumentationspaket für Self-Service-API-Implementierung und Review. Diese Seite fasst den öffentlichen API-Vertrag, das Zugangsmodell und die Integrationsvorgaben zusammen. ## Überblick Technisches Dokumentationspaket für Self-Service-API-Implementierung und Review. Diese Seite fasst den öffentlichen API-Vertrag, das Zugangsmodell und die Integrationsvorgaben zusammen. Die API akzeptiert Multipart-Uploads, liefert JSON-Antworten zurück und nutzt Standard-HTTP-Statuscodes sowie Bearer-Authentifizierung. Senden Sie eine PDF-Rechnung, warten Sie auf die asynchrone Verarbeitung und rufen Sie dann das erzeugte Ergebnis ab. Senden Sie eine PDF-Rechnung 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: freigabepflichtig**: Basispfad: /api/v1. Zuletzt synchronisiert 2026-06-29. ## 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 ## 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) ## 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) PDF-Rechnung konvertieren ### POST /api/v1/invoices:convert-structured (Live) Strukturierte Daten konvertieren ### GET /api/v1/tasks/{task_id} (Live) Task-Status abfragen ## API-Zugang erhalten - Erstellen Sie ein Konto und beantragen Sie API-Zugang. - Nutzen Sie Prepaid-API-Credits für freigegebene Tests oder Enterprise-Abrechnung per Order Form für produktive Nutzung. - Erstellen Sie nach Freigabe einen Live-API-Schlüssel für Ihren Tenant. - Senden Sie die erste Anfrage mit Bearer-Token und stabilem Idempotency-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 freigegebene 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` und `format=XRECHNUNG`. - Alle `10-15 Sekunden` pollen: `GET /api/v1/tasks/{task_id}`, bis der Status `completed` oder `failed` ist. - 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. - 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; für deterministische Integrationen ein explizites `profile` wie `PEPPOL`, `XRECHNUNG` oder `EN16931` setzen. - `CII`: `format=CII` senden; für deterministische Integrationen ein explizites `profile` wie `EN16931` setzen. ## Erforderliche Header - Authorization: Bearer ## Auth-Regeln Der API-Zugang ist freigabepflichtig. Freigegebene Accounts können API-Schlüssel im Profil erstellen, sie als Bearer-Token verwenden und Prepaid-Credits für freigegebene Tests oder Enterprise-Abrechnung per Order Form für Produktion nutzen. - API-Schlüssel sind tenant-gebundene Live-Zugangsdaten für freigegebene Accounts. Das aktuelle Produktionspräfix ist `icp_...`. - API-Schlüssel werden nach Freigabe des API-Zugangs im Profil erstellt, rotiert und widerrufen. 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`. - Idempotenzschlüssel laufen nach `24 Stunden` ab. ## 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 eine PDF-Rechnung hoch und starten Sie die asynchrone Konvertierung. Gibt eine task_id für das Polling zurück. Anfrage: multipart/form-data; file (binary, erforderlich) — PDF-Rechnungsdatei; format (string, erforderlich) — Zielausgabeformat; siehe Formatmatrix unten; profile (string, optional, empfohlen für deterministische Integrationen) — explizites Compliance-Profil. Standardwerte richten sich nach dem Format; erlaubte Werte sind unter anderem XRECHNUNG, PEPPOL, EN16931 und unterstützte ZUGFeRD/Factur-X-Profile; 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. 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. Standard wird anhand des Formats gewählt; 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. Antwort: 202 Accepted. ### GET /api/v1/tasks/{task_id} (Live) Fragen Sie den aktuellen Status eines Konvertierungs-Tasks ab. Gibt pending, processing, completed oder failed zurück. 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. 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. 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. Wiederholte Downloads können aus zwischengespeicherten Artefakten bedient werden, wenn der Validierungsnachweis noch aktuell ist. Während der Verarbeitung liefert der Endpunkt 202 TASK_NOT_READY; bei blockierenden Validierungsfehlern 422 VALIDATION_FAILED, bei wiederholbaren Abhängigkeitslücken 503 und bei Artefakt-Invariantfehlern 500, jeweils ohne Dateiinhalt. 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. 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.4 / Factur-X 1.08 | 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 | ## Änderungsprotokoll Neueste extern sichtbare API-Änderungen. ### 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-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-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. ### 2026-02-20 Statusantworten auf statusfokussierte Ausgabe vereinfacht. IndexNow-Submission-Validierung und Authentifizierungsprüfungen gehärtet. API-Zugriffskontrollen und Request-Limiting in Produktion gehärtet. ## 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 | | INSUFFICIENT_API_CREDITS | 402 | Nein | Freigegebene Prepaid-Testcredits oder Enterprise-Abrechnung per Order Form nutzen | | IDEMPOTENCY_KEY_REQUIRED | 400 | Nein | Schreibendpunkt ohne Idempotency-Key aufgerufen | | INVALID_IDEMPOTENCY_KEY | 400 | Nein | Idempotency-Key hat ein ungültiges Format | | IDEMPOTENCY_CONFLICT | 409 | Nein | Derselbe Key wurde mit anderem Request-Hash verwendet | | IDEMPOTENCY_IN_PROGRESS | 409 | Ja | Sicherer Retry später mit demselben Key/Payload möglich | | 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 | | 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 | Rate-Limit-Backend nicht verfügbar | | RATE_LIMITED | 429 | Ja | Retry-After und Kontingent-Header beachten | | BAD_REQUEST | 400 | Nein | Ungültiges JSON oder ungültiger UUID-Pfadparameter | | PAYLOAD_TOO_LARGE | 413 | Nein | Upload-Größenlimit überschritten | | INVALID_UPLOAD | 400 | Nein | Upload konnte nicht gelesen/geparst werden | | UPLOAD_FAILED | 4xx/5xx | Bedingt | Ungültige Request-Optionen korrigieren; Retry nur bei transienten 5xx-Fällen | | TASK_NOT_READY | 202 | Ja | Für asynchrone Fertigstellung erneut pollen | | VALIDATION_FAILED | 422 | Nein | Blockierende Validierungsfehler bestehen weiterhin; 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 | | 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 | | ZUGFERD_SOURCE_PDF_INCOMPATIBLE | 422 | Nein | Strikte Hybrid-PDF-Erzeugung kann XML nicht in das hochgeladene Quell-PDF einbetten | | 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 | Temporärer Verbindungsfehler (504 bei Timeout) | ## Häufige Fehler und nächste Schritte - Mit Backoff erneut versuchen: `429`, `500`, `502`, `503`, `504`. - Request oder Quelldaten korrigieren: `400`, `409`, `413`, `422`. - Zugang oder Zugangsdaten korrigieren: `401`, `403`. - Freigabe, Prepaid-Testcredits oder Enterprise-Abrechnung per Order Form klären: `402 INSUFFICIENT_API_CREDITS`. - Später weiter pollen: `202 TASK_NOT_READY`. - 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. ## 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. Beide Upload-Endpunkte nutzen das Basiskontingent (Standard `30/min` und `500/hour`); Task-Polling liegt aktuell standardmäßig bei mindestens `10/min` und `120/hour`, Result-Downloads bei mindestens `10/min` und ungefähr `134/hour`. - Lesen Sie effektive Limits aus `X-RateLimit-Limit-Minute` und `X-RateLimit-Limit-Hour` in den Antworten. - Maximale PDF-Uploadgröße: `20 MB` - Maximale Uploadgröße strukturierter Daten: `2 MB` insgesamt über alle `data_file`-Parts. - Maximale JSON-Payloadgröße: `1 MB` - Rate-Limit-Antworten enthalten `Retry-After`, `X-RateLimit-Limit-Minute` und `X-RateLimit-Limit-Hour`. ## Retry-Leitfaden - Verwenden Sie exponentielles Backoff mit Jitter. - Wiederholen Sie nur transiente Klassen (`429`, `500`, `502`, `503`, `504`) und möglichst mit demselben Payload und Idempotency-Key. - Wiederholen Sie Validierungs- oder Vertragsfehler (`400`, `401`, `402`, `403`, `409`, `413`, `422`) nicht blind. ## Task-Lebenszyklus und Aufbewahrung - Abgeschlossene und fehlgeschlagene Tasks bleiben nach Erreichen des Endstatus `10 Minuten` verfügbar. - Die Verarbeitung läuft nach `5 Minuten` in ein Timeout; festhängende Tasks werden automatisch als `failed` markiert. - Idempotenzschlüssel laufen nach `24 Stunden` ab. - 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. ## 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) ## Postman und OpenAPI verwenden - Postman-Collection importieren und `baseUrl`, `apiKey` sowie eine neue Variable `idempotencyKey` 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.