# Externe API V1 Dokumentation Technisches Dokumentationspaket für Self-Service-API-Implementierung und Review. Diese Seite fasst den externen API-Vertrag, das Zugangsmodell und Integrationsvorgaben zusammen. ## Überblick Technisches Dokumentationspaket für Self-Service-API-Implementierung und Review. Diese Seite fasst den externen API-Vertrag, das Zugangsmodell und 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 an einen einzelnen Endpoint. Invoice-Converter übernimmt Extraktion, Validierung und Ausgabeerzeugung. Der Ergebnis-Endpoint liefert die erzeugte Datei erst, wenn alle Validierungsgates bestanden sind; andernfalls gibt er 422 VALIDATION_FAILED zurück. > **Status: self-service**: Basispfad: /api/v1. Zuletzt synchronisiert 2026-05-23. ## Wichtige Funktionen - 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. - [OpenAPI JSON](/developer-api/v1/openapi.json) - [Postman-Kollektion](/developer-api/v1/postman.json) - [API Playground](/developer-api/playground) ## 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 (In Entwicklung) PDF in strukturierte E-Rechnung konvertieren ### GET /api/v1/tasks/{task_id} (In Entwicklung) Task-Status abfragen ### GET /api/v1/tasks/{task_id}/result (In Entwicklung) Konvertierungsergebnis herunterladen ## Closed-Beta-Zugang anfragen - 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 - 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 - `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 - Authorization: Bearer ## 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 - 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. ### POST /api/v1/invoices:convert (In Entwicklung) 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. Antwort: 202 Accepted. ### GET /api/v1/tasks/{task_id} (In Entwicklung) Fragen Sie den aktuellen Status eines Konvertierungs-Tasks ab. Gibt pending, processing, completed oder failed zurück. Bei failed enthält die Antwort ein error-Feld mit dem Fehlergrund. Anfrage: keins (GET). Antwort: 200 OK. ### GET /api/v1/tasks/{task_id}/result (In Entwicklung) Laden Sie die erzeugte Datei herunter. ZUGFERD-Tasks liefern standardmäßig ein EN16931 ZUGFeRD/Factur-X Hybrid-PDF; andere Formate liefern standardmäßig XML. Wiederholte Downloads können aus zwischengespeicherten Artefakten bedient werden. Wenn blockierende Validierungsfehler bestehen, gibt dieser Endpoint 422 VALIDATION_FAILED ohne Dateiinhalt zurück. Anfrage: keins (GET). Antwort: 200 OK. ## Matrix der Ausgabeformate | Format | Syntax | Version / Profil | Content-Type | Dateiendung | | --- | --- | --- | --- | --- | | XRECHNUNG | UBL 2.1 XML | XRechnung 3.0.2 | application/xml | .xml | | ZUGFERD | Standardmäßig EN16931 Hybrid-PDF/A-3; CII-XML mit download=xml | ZUGFeRD 2.4 / Factur-X 1.08 | application/pdf oder application/xml | .pdf / .xml | | 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-05-08 Prepaid-API-Credits für Nicht-Enterprise-Mandanten ergänzt. 402 INSUFFICIENT_API_CREDITS für Mandanten ohne Enterprise-Abrechnung oder Prepaid-Credits dokumentiert. Bestätigt, dass idempotente Replays keine zusätzlichen API-Credits verbrauchen. Convert-Requests auf Datei plus Format vereinfacht; Extraktionssteuerung wird serverseitig verwaltet. ### 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 Endpoints 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-Key nicht gefunden, widerrufen oder abgelaufen | | INSUFFICIENT_API_CREDITS | 402 | Nein | Mindestens 10 Prepaid-API-Credits kaufen oder Enterprise-Abrechnung nutzen | | IDEMPOTENCY_KEY_REQUIRED | 400 | Nein | Schreib-Endpoint 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 | | 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 | | 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 | Transiente XML-Erzeugungsstörung oder Timeout | | PDF_GENERATION_FAILED | 500 | Ja | Transiente PDF-Erzeugungsstörung oder Timeout | | PROFILE_MISMATCH | 422 | Nein | Invoice CustomizationID conflicts with the selected public format | | 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`. - 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 - 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 - 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 - 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. - [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)%2520%0D%0A2)%2520%0D%0A3)%2520%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.