Externe API V1 Dokumentation

Wichtige Funktionen#

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

• Ein einzelner Endpoint für die PDF-zu-XML-Konvertierung
• KI-gestützte Extraktion von Rechnungsdaten
• Automatisierte EN 16931- und KoSIT-Validierung
• Ausgabeformate XRechnung, ZUGFeRD, UBL und CII
• Asynchrone Verarbeitung mit Polling, kleine Rechnungen ca. 30 Sekunden und 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.

Closed-Beta-Zugang anfragen#

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

• Melden Sie sich an und öffnen Sie den Profilbereich.
• Kaufen Sie Prepaid-API-Credits oder nutzen Sie einen Enterprise-Plan mit enthaltenem API-Zugang.
• Erstellen Sie einen API-Key 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://invoice-converter.com/api/v1.
• Nutzen Sie denselben Produktions-API-Host für den gesamten Pilot-Traffic: https://invoice-converter.com/api/v1.
• Nutzen Sie im Onboarding kleine Fixture-Anfragen; akzeptierte Konvertierungsanfragen verbrauchen API-Credits.
• Behandeln Sie Keys 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-Keys.

• Hochladen: POST /api/v1/invoices:convert mit Authorization, Idempotency-Key, file=@invoice.pdf und format=XRECHNUNG.
• Alle 2-5 Sekunden pollen: GET /api/v1/tasks/{task_id}, bis der Status completed oder failed ist.
• Herunterladen: GET /api/v1/tasks/{task_id}/result; speichern Sie X-Correlation-ID und, falls vorhanden, X-Validation-Proof-Id.
• Für ZUGFeRD-PDF-Ausgabe format=ZUGFERD senden; der Result-Endpoint liefert standardmäßig das Hybrid-PDF.

Häufige Payload-Beispiele#

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

• XRECHNUNG: format=XRECHNUNG senden; dies ist der Standard, wenn format fehlt.
• ZUGFERD: format=ZUGFERD für ein EN16931 ZUGFeRD/Factur-X Hybrid-PDF senden.
• UBL: format=UBL für EN16931 UBL-XML senden.
• CII: format=CII für EN16931 CII-XML senden.

Erforderliche Header#

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

• Authorization: Bearer <api_key>

Auth-Regeln#

Der API-Zugang ist im Self-Service verfügbar. Erstellen Sie API-Keys im Profil, verwenden Sie diese als Bearer-Token und kaufen Sie Prepaid-API-Credits für Konvertierungsautomatisierung.

• Keys sind tenant-gebunden und verwenden das Präfix icp_.
• Keys werden im Profil erstellt, rotiert und widerrufen, sobald der External-API-Zugang aktiviert ist. Kopieren Sie neue Keys sofort, weil Klartext-Keys nur einmal angezeigt werden.
• Fehlende oder ungültige Keys 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-Keys 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.
• Idempotency-Keys laufen nach 24 hours ab.

Endpoint-Referenz#

Alle Endpoints sind unter /api/v1 erreichbar. Timeouts erscheinen als 504 und andere temporäre Verbindungsfehler als 502; Korrelations-IDs helfen dem Support bei der Nachverfolgung Ende-zu-Ende.

Matrix der Ausgabeformate#

Ä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.
• Später weiter pollen: 202 TASK_NOT_READY.
• Bei 422 VALIDATION_FAILED Feld, Regel-ID und Remediation einem menschlichen Reviewer zeigen, bevor mit korrigierten Rechnungsdaten erneut versucht wird.

Rate- und Payload-Limits#

Rate-Limits pro Key und Payload-Größen gelten für alle API-Aufrufe. Abgelehnte Requests verbrauchen kein Kontingent.

• Endpoint-bezogene Kontingente sind kostenbewertet. Convert nutzt das Basiskontingent des Plans (Standard 30/min und 500/hour), während Polling-Endpoints niedriger gewichtet sind.
• Lesen Sie effektive Limits aus X-RateLimit-Limit-Minute und X-RateLimit-Limit-Hour in den Antworten.
• Maximale PDF-Uploadgröße: 20 MB
• 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, 403, 409, 413) 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 minutes verfügbar.
• Die Verarbeitung läuft nach 5 minutes in ein Timeout; festhängende Tasks werden automatisch als failed markiert.
• Idempotency-Keys laufen nach 24 hours 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 während der Geschäftszeiten.
• Ziel für erste Antwort: 1 Werktag.

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.