External API V1 Documentation

Overview

Key capabilities

• Single endpoint for PDF-to-XML conversion
• AI-powered invoice data extraction
• Automated EN 16931 and KoSIT validation
• XRechnung, ZUGFeRD, UBL, and CII output formats
• Async processing with polling - results in 5-15 seconds
• Idempotent writes for safe retries

Delivery Artifacts

Download machine-readable integration artifacts for the Developer API.

Quickstart

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

Required request headers

• Authorization: Bearer <api_key>

Auth rules

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.

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

Endpoint Reference

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.

Output format matrix

Changelog

Recent externally visible API changes.

Error Contract

Rate & 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 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`).

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.

Support model

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

Send Technical Feedback

Share implementation questions, risks, and required contract changes with our team.