External API V1 Documentation

Key capabilities#

Use these points as the practical checks for this section.

• 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 - small invoices around 30 seconds, larger invoices up to 1-2 minutes
• 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.

Request closed beta access#

Use these points as the practical checks for this section.

• Create an account and open your profile.
• Buy prepaid API credits or use an Enterprise plan with included API access.
• Create an API key from the API access section.
• Run the first request with server-side credentials, then monitor usage and rotate keys from your profile.

Base URL and API keys#

Use these points as the practical checks for this section.

• Production base URL: https://invoice-converter.com/api/v1.
• Use the same production API host for all pilot traffic: https://invoice-converter.com/api/v1.
• Use low-volume fixture requests during onboarding; accepted conversion requests consume API credits.
• Treat keys as server-side secrets. Do not embed them in browser or mobile clients.

First successful request#

Use this sequence as the minimum happy path after creating an API key.

• Upload: POST /api/v1/invoices:convert with Authorization, Idempotency-Key, file=@invoice.pdf, and format=XRECHNUNG.
• Poll every 2-5 seconds: GET /api/v1/tasks/{task_id} until status is completed or failed.
• Download: GET /api/v1/tasks/{task_id}/result and store X-Correlation-ID plus X-Validation-Proof-Id when present.
• For ZUGFeRD PDF output, send format=ZUGFERD; the result endpoint defaults to the hybrid PDF.

Common payload examples#

Use these points as the practical checks for this section.

• XRECHNUNG: send format=XRECHNUNG; this is the default when format is omitted.
• ZUGFERD: send format=ZUGFERD for an EN16931 ZUGFeRD/Factur-X hybrid PDF.
• UBL: send format=UBL for EN16931 UBL XML.
• CII: send format=CII for EN16931 CII XML.

Required request headers#

Use these points as the practical checks for this section.

• Authorization: Bearer <api_key>

Auth rules#

API access is self-serve. Create API keys from your profile, use them as Bearer tokens, and buy prepaid API credits for conversion automation.

• Keys are tenant-scoped and use the icp_ prefix.
• Create, rotate, and revoke API keys from your profile when External API access is enabled. Copy new keys immediately because plaintext keys are shown only once.
• Missing or invalid key returns 401.
• Calls to /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#

Use these points as the practical checks for this section.

• 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 available under /api/v1. Timeouts surface as 504 and other temporary connectivity failures as 502; correlation IDs help support trace requests end-to-end.

Output format matrix#

Changelog#

Recent externally visible API changes.

Error Contract#

Common errors and what to do#

Use these points as the practical checks for this section.

• Retry with backoff: 429, 500, 502, 503, 504.
• Fix request or source data: 400, 409, 413, 422.
• Fix access or credentials: 401, 403.
• Keep polling later: 202 TASK_NOT_READY.
• For 422 VALIDATION_FAILED, show the returned field, rule ID, and remediation to a human reviewer before retrying with corrected invoice data.

Rate & payload limits#

Per-key rate limits and payload size constraints are enforced for all API calls. Denied requests do not consume quota.

• 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 these points as the practical checks for this section.

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

Use these points as the practical checks for this section.

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

Use these points as the practical checks for this section.

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

Send Technical Feedback#

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

Use Postman and OpenAPI#

Use these points as the practical checks for this section.

• Import the Postman collection and set baseUrl, apiKey, and a new idempotencyKey variable.
• Run the collection in order: convert, poll status, then fetch result.
• Use the OpenAPI JSON to generate typed clients, but keep file upload, polling, and binary result handling covered by integration tests.
• Record X-Correlation-ID in logs so support can trace requests end-to-end.