Externe API V1 Dokumentation

Überblick

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, Ergebnisse in 5-15 Sekunden
• Idempotente Schreibzugriffe für sichere Wiederholungen

Lieferartefakte

Laden Sie maschinenlesbare Integrationsartefakte für die Developer API herunter.

Schnellstart

Three API calls complete a conversion. The convert endpoint is served at /api/v1 and requires authentication.

Erforderliche Header

• Authorization: Bearer <api_key>

Auth-Regeln

Use your API key as a Bearer token. Keys are provisioned in your account settings under Profile → API keys.

• Keys are tenant-scoped and environment-scoped (`live` / `test`). Key prefix determines environment.
• Provision or rotate keys under `Profile` → `API keys` in your account, or contact support.
• Missing or invalid key returns `401`.
• Calls via the website proxy (`/api/v1`) receive an `X-Correlation-ID` automatically when omitted.
• Write calls require `Idempotency-Key`; keep this value stable across retries.
• Use server-to-server integration from your backend. Browser-origin access is restricted in production.

Idempotenz-Vertrag

• Send an `Idempotency-Key` on every write call.
• Idempotency keys must match `[A-Za-z0-9._:-]+` and be at most 200 chars.
• If you provide your own key, the same key + identical payload returns the cached response.
• Same key + different payload returns `409 IDEMPOTENCY_CONFLICT`.
• Idempotency keys expire after `24 hours`.

Endpoint-Referenz

All endpoints are served through the website proxy at /api/v1. Upstream timeouts surface as 504 and other proxy connectivity failures as 502; correlation IDs propagate end-to-end for traceability. Trusted-host and origin controls are enforced in production deployments.

Matrix der Ausgabeformate

Änderungsprotokoll

Neueste extern sichtbare API-Änderungen.

Fehlervertrag

Rate- und Payload-Limits

Per-key rate limits and payload size constraints are enforced at the proxy layer. Denied requests do not consume quota. Proxy-header trust is fail-closed by default unless explicitly enabled for trusted infrastructure.

• Endpoint-aware quotas are cost-weighted. Convert uses the baseline plan quota (default `30/min` and `500/hour`), while polling endpoints use lower weighted quotas.
• Read effective limits from `X-RateLimit-Limit-Minute` and `X-RateLimit-Limit-Hour` on responses.
• PDF upload max size: `20 MB`
• JSON payload max size: `1 MB`
• Rate-limit responses include `Retry-After`, `X-RateLimit-Limit-Minute`, and `X-RateLimit-Limit-Hour`.

Retry-Leitfaden

• Use exponential backoff with jitter.
• Retry only transient classes (`429`, `500`, `502`, `503`, `504`) using the same payload and idempotency key where possible.
• Do not blindly retry validation or contract errors (`400`, `401`, `403`, `409`, `413`).

Task-Lebenszyklus und Aufbewahrung

• Completed and failed tasks remain available for `10 minutes` after reaching terminal state.
• Processing times out after `5 minutes` — stuck tasks are automatically marked `failed`.
• Idempotency keys expire after `24 hours`.
• Rate-limit counters reset on a rolling window.

Supportmodell

• Business-hours support.
• Target first response: 1 business day.

Technisches Feedback senden

Teilen Sie Implementierungsfragen, Risiken und erforderliche Vertragsänderungen mit unserem Team.