Integration
Markdown-ExportExterne 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.
- Erstellen Sie ein Konto und starten Sie Enterprise auf der Preisseite: 35 €/Monat bei jährlicher Abrechnung (420 €/Jahr); bei monatlicher Abrechnung: 50 €/Monat.
- Nutzen Sie die 100 monatlich enthaltenen gemeinsamen E-Mail/API-Konvertierungen; weitere Konvertierungen kosten über Prepaid-Credits je 0,40–0,50 €.
- Erstellen Sie im API-Bereich Ihres Profils einen Live-API-Schlüssel.
- Senden Sie die erste Anfrage mit Bearer-Token und stabilem Idempotency-Key.
Enterprise starten
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
LiveRechnungsdokument konvertieren
POST /api/v1/invoices:convert-structured
LiveStrukturierte Daten konvertieren
GET /api/v1/tasks/{task_id}
LiveTask-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.
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"curl "https://www.invoice-converter.com/api/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $API_KEY"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:convertmitAuthorization,Idempotency-Key,file=@invoice.pdf(oder.docx/.txt) undformat=XRECHNUNG. - Mit Backoff pollen: nach dem
202etwa20 Sekundenwarten, dannGET /api/v1/tasks/{task_id}in Abständen von 20s, 30s, 45s, 60s und 60s aufrufen, bis der Statuscompletedoderfailedist. Bleiben Sie im Kontingent von10/minund120/hourund brechen Sie nach etwa 16 Minuten ab. - Herunterladen:
GET /api/v1/tasks/{task_id}/result?download=xml; speichern SieX-Correlation-IDfür den Support-Trace. - Für ZUGFeRD-PDF-Ausgabe beim Convert
format=ZUGFERDund beim Resultdownload=pdfanfragen; Hybrid-PDF-Ausgabe erfordert einen PDF-Quellupload. - Für strukturierte Eingaben rufen Sie
POST /api/v1/invoices:convert-structuredmitpdf_file=@invoice.pdf,data_file=@invoice-data.jsonund dem Ziel-formatauf. - Optional
client_referenceoderexternal_invoice_idundsource_systemfü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_artifactsaus 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=XRECHNUNGsenden.ZUGFERD:format=ZUGFERDsenden; für hybrides PDF/A-3 im Resultdownload=pdfnutzen.Strukturierte Eingabe:pdf_fileplus ein oder mehreredata_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ückgegebenetask_idnachverfolgen; wiederholtedata_file-Parts sind nur für gesplittete Exporte derselben Rechnung gedacht.UBL:format=UBLsenden; zulässige Profile sindXRECHNUNG,PEPPOLundEN16931, Standard istEN16931.CII:format=CIIsenden; zulässige Profile sindXRECHNUNG,EN16931,ZUGFERD_EN16931,ZUGFERD_FACTURX_EXTENDEDundZUGFERD_XRECHNUNG, Standard istEN16931.formatxprofileist eine abgeschlossene Tabelle:XRECHNUNGakzeptiert[XRECHNUNG](StandardXRECHNUNG),EN16931akzeptiert[EN16931](StandardEN16931),UBLakzeptiert[XRECHNUNG, PEPPOL, EN16931](StandardEN16931),CIIakzeptiert[XRECHNUNG, EN16931, ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG](StandardEN16931) undZUGFERDakzeptiert[ZUGFERD_EN16931, ZUGFERD_FACTURX_EXTENDED, ZUGFERD_XRECHNUNG](StandardZUGFERD_EN16931). Profile werden ohne Beachtung der Groß-/Kleinschreibung zugeordnet;ZUGFERD,FACTURX,FACTUR-XundFACTUR_Xsind Aliase fürZUGFERD_EN16931,ZUGFERD-XRECHNUNGist ein Alias fürZUGFERD_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/v1erhalten automatisch eineX-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 nach15 Minutenfreigegeben. - 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 Stundenund 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
LiveLaden 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
LiveLaden 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}
LiveFragen 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
LiveLaden 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
LiveLaden 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
| 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.5 / Factur-X 1.09 | 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 | Der Schlüssel ist gültig, aber der External-API-Zugang ist für dieses Konto deaktiviert; Support kontaktieren |
| 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 | Der ursprüngliche Task liegt außerhalb der 24-Stunden-Aufbewahrung; neue Konvertierung mit neuem Schlüssel starten |
| 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_EMAIL_INPUT | 400 | Nein | email_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_POLICY | 400 | Nein | use_embedded_xml muss true oder false sein |
| INVALID_SELLER_MASTER_DATA | 400 | Nein | use_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_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 oder API-Zugang konnten nicht geprüft werden; mit Backoff erneut versuchen |
| 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 | Unbekannter Profilname; details.allowed_profiles enthält die zulässigen Werte |
| 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 | Endgültig: Die Quelle enthält mehrere Rechnungen. In eine Datei pro Rechnung teilen und getrennte Konvertierungen starten |
| NO_INVOICE_DETECTED | 500 (details code) | Nein | Endgültig: Das Dokument scheint keine Rechnung zu sein; manuell bearbeiten |
| INSUFFICIENT_INVOICE_SIGNAL | 500 (details code) | Nein | Endgültig: Die Quelle enthält zu wenig Rechnungsdaten; bessere Quelle senden oder strukturierte Konvertierung nutzen |
| SCHEMA_PARSE_FAILED | 500 (details code) | Nein | Für diese Eingabe endgültig: Extrahierte Daten konnten nicht in das Schema eingelesen werden. Neue Konvertierung starten; bei Wiederholung mit demselben Dokument eskalieren |
| PROVIDER_ERROR | 500 (details code) | Bedingt | Extraktionsanbieter fehlgeschlagen. details.retryable beachten; bei provider_context_too_large ein kleineres Quelldokument nutzen |
| 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 | Mindestens eine Extraktionsgruppe ist fehlgeschlagen. Der Task kann sich nicht erholen; neue Konvertierung starten und details.failed_groups prüfen |
| 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,503mit wiederholbarem Code sowie transiente500-Fehler, die nichtTASK_FAILEDoderINTERNAL_ARTIFACT_INVARIANT_FAILEDsind.500 TASK_FAILEDist nur wiederholbar, wenndetails.retryabletrueist, 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, wenndetails.retryablenichttrueist, und500 INTERNAL_ARTIFACT_INVARIANT_FAILED. - Request oder Quelldaten korrigieren:
400,413,422. - Zugang oder Zugangsdaten korrigieren:
401 INVALID_API_KEY.403 API_NOT_ENABLED_FOR_TENANTbedeutet, 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 vorhandenendetails-Schlüssel (remainingbei Prepaid-Accounts oderincluded_remaining/credit_remaining/shortfall, wenn ein enthaltenes Kontingent greift). - Später weiter pollen:
202 TASK_NOT_READY. - Bei
500 TASK_FAILEDdetails.codeunddetails.retryableauswerten.MULTIPLE_INVOICES_IN_DOCUMENT,NO_INVOICE_DETECTED,INSUFFICIENT_INVOICE_SIGNAL,SCHEMA_PARSE_FAILEDundARTIFACT_PARITY_FAILEDsind endgültig;PROVIDER_ERRORund jeder unbekannte Code richten sich nachdetails.retryable, undtruebedeutet eine NEUE Konvertierung statt eines erneuten Pollings desselben Tasks. Eine fehlgeschlagene Konvertierung verbraucht keine Abrechnungseinheit. - Bei
422 VALIDATION_FAILEDdas 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_UNAVAILABLEdenselben Task später erneut abrufen; es wurde kein ungeprüftes Artefakt ausgeliefert. Bei503 ARTIFACT_GENERATION_RERUN_REQUIREDund503 EXTRACTION_INCOMPLETE_GROUP_FAILUREstattdessen eine neue Konvertierung starten. 502und504 PROXY_ERRORsind 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:convertundPOST /invoices:convert-structured30/minund500/hour;GET /tasks/{task_id}10/minund120/hour;GET /tasks/{task_id}/result10/minund etwa134/hour;GET /tasks/{task_id}/validation-report10/minund120/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 einer429-Antwort. - Der Status-Bucket ist die bindende Grenze für das Polling: Warten Sie nach dem angenommenen
202etwa20 Sekundenbis zum ersten Statusaufruf, erhöhen Sie danach die Abstände (20s, 30s, 45s, 60s und ab dann 60s) und beenden Sie das Polling beicompletedoderfailed. 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 MBfür PDF-, DOCX- oder TXT-Dateien. - Maximale Uploadgröße strukturierter Daten:
2 MBinsgesamt über alledata_file-Parts. - Maximale JSON-Payloadgröße:
1 MB 429-Antworten enthaltenRetry-After,X-RateLimit-Limit-MinuteundX-RateLimit-Limit-Hoursowiedetails.minute_count,details.hour_count,details.limit_minuteunddetails.limit_hour.
Retry-Leitfaden
- Verwenden Sie exponentielles Backoff mit Jitter und denselben
Idempotency-Keybei jedem Retry eines Schreib-Requests. - Entscheiden Sie anhand des maschinenlesbaren
code— und bei500 TASK_FAILEDanhand vondetails.codeplusdetails.retryable— nie allein anhand des HTTP-Status. Ein500ist in dieser API nicht automatisch wiederholbar. - Wiederholbar:
429,502,504,503mit wiederholbarem Code, transiente500-Fehler, die NICHTTASK_FAILEDoderINTERNAL_ARTIFACT_INVARIANT_FAILEDsind, sowie500 TASK_FAILED, wenndetails.retryabletrueist (transiente Provider-Fehler: Rate-Limit, Timeout, Transportfehler) — dieser Fall wird als NEUE Konvertierung mit neuemIdempotency-Keywiederholt, 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, wenndetails.retryablenichttrueist, und500 INTERNAL_ARTIFACT_INVARIANT_FAILED. Eine endgültig fehlgeschlagene Konvertierung verbraucht keine Abrechnungseinheit. 409 IDEMPOTENCY_IN_PROGRESSist mit DEMSELBEN Key nach kurzer Wartezeit wiederholbar; ein hängender In-Progress-Anspruch wird nach 15 Minuten freigegeben.503 ARTIFACT_GENERATION_RERUN_REQUIREDund503 EXTRACTION_INCOMPLETE_GROUP_FAILUREerfordern eine NEUE Konvertierung statt eines Retrys desselben Tasks.
Task-Lebenszyklus und Aufbewahrung
- Ein Task und seine gespeicherten Artefakte werden
24 Stundennach Erreichen eines Endstatus (completedoderfailed) aufbewahrt und danach gelöscht. Nach der Löschung liefern Status-, Ergebnis- und Validierungsbericht-Anfragen404 TASK_NOT_FOUND. - Es gibt kein festes Konvertierungs-Timeout. Ein Task schlägt fehl, wenn
5 Minutenlang kein Stufen- oder Fortschrittsupdate erfolgt (Stillstandsfenster) oder wenn die gesamte Verarbeitung die absolute Obergrenze von15 Minutenüberschreitet. - Setzen Sie Ihr clientseitiges Timeout auf etwa
16 Minutenab dem angenommenen202. Die meisten Konvertierungen sind deutlich unter zwei Minuten fertig. - Idempotenz-Datensätze bestehen
24 Stundenund entsprechen damit der Task-Aufbewahrung. Ein hängender Request wird nach15 Minutenfreigegeben. - 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_keyundidempotency_keysetzen. - 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-IDin Logs speichern, damit Support Requests Ende-zu-Ende nachverfolgen kann.
Technisches Feedback senden
Teilen Sie Implementierungsfragen, Risiken und erforderliche Vertragsänderungen mit unserem Team.