Invoice-Converter API

2026-03-06

• Made task-result downloads format-faithful for CII and ZUGFERD outputs.
• Added cached result artifact reuse for repeated XML/PDF downloads of the same task.
• Aligned polling quotas with endpoint-scoped weighted rate-limit buckets.

2026-02-23

• Added clearer, consistent API error responses across all endpoints.
• Expanded convert options and documented XML/PDF download behavior for task results.
• Improved retry safety with stricter idempotency requirements and validation.
• Updated OpenAPI/Postman artifacts to match current API behavior.

2026-02-20

• Simplified public health endpoint responses to status-focused output.
• Strengthened IndexNow submission validation and authentication checks.
• Hardened API access controls and request-limiting behavior in production.

Auth rules

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

Idempotency contract

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

Missing mandatory field examples

• Convert returns 202 Accepted when file intake succeeds.
• Mandatory-field validation happens during async processing.
• The result endpoint returns a file only when validation passes.
• Blocking validation issues return 422 VALIDATION_FAILED with structured details.
• Unreadable/empty PDF → immediate 400 INVALID_UPLOAD.

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "correlation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "details": {
    "type": "validation",
    "items": [
      {
        "field": "BuyerReference",
        "rule_id": "BR-DE-15",
        "severity": "error",
        "source": "task-result-download",
        "suggestion": "Provide Leitweg-ID / BuyerReference."
      }
    ]
  }
}

Rate & payload limits

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

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

Polling state machine

Poll GET /api/v1/tasks/{task_id} every 2–5 seconds. Stop when status reaches a terminal state.

Task lifecycle & retention

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