Externe API V1 Dokumentation

Wichtige Funktionen#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

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

Schnellstart#

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

API-Zugang erhalten#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• 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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• 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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• 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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• Authorization: Bearer <api_key>

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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

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

Ausgabeformat-Matrix#

Änderungsprotokoll#

Neueste extern sichtbare API-Änderungen.

Fehlervertrag#

Häufige Fehler und nächste Schritte#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• 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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• 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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

• 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#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

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

Postman und OpenAPI verwenden#

Nutzen Sie diese Punkte als praktische Prüfschritte für diesen Abschnitt.

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