Externe API V1 Dokumentation

Rechnungsdokument konvertieren

Strukturierte Daten konvertieren

Task-Status abfragen

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. 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; 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.

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; 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.

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. 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.