Documentverwerking, afgerekend per pagina.

Snel beginnen

Maak onder Account → API-sleutels een sleutel. Kies Sandbox voor een kosteloze dxk_test_-sleutel of Live voor dxk_live_. Upload daarna een bestand, maak een taak, controleer de status en download het resultaat.

# 1. Upload
curl -s https://docaxo.com/api/v1/files \
  -H "Authorization: Bearer $DOCAXO_API_KEY" \
  -F "[email protected]"
# → {"id":"f_…","object":"file","page_count":3,"status":"ready",…}

# 2. Start a job (safe to retry thanks to Idempotency-Key)
curl -s https://docaxo.com/api/v1/jobs \
  -H "Authorization: Bearer $DOCAXO_API_KEY" \
  -H "Idempotency-Key: order-42-ocr" \
  -H "Content-Type: application/json" \
  -d "{\"operation\":\"ocr\",\"file_id\":\"$FILE_ID\",\"options\":{\"mode\":\"base\"}}"
# → 202 {"id":"…","status":"queued","credits":{"billed":true,"pages_estimated":3},…}

# 3. Poll, then download
curl -s "https://docaxo.com/api/v1/jobs/$JOB_ID" -H "Authorization: Bearer $DOCAXO_API_KEY"
curl -sL "https://docaxo.com/api/v1/jobs/$JOB_ID/result?format=json" \
  -H "Authorization: Bearer $DOCAXO_API_KEY" -o blocks.json

Gebruik voor pushmeldingen een webhook en wacht op job.succeeded. De machineleesbare specificatie staat op /api/v1/openapi.json.

Authenticatie

Stuur de sleutel als Bearer-token: Authorization: Bearer dxk_live_…. Browsercookies worden op /api/v1 niet geaccepteerd. Het voorvoegsel bepaalt de modus: dxk_test_ voor sandbox en dxk_live_ voor liveverwerking en facturering.

• Live-sleutels vereisen API Starter; sandbox werkt bij elk abonnement.
• Scopes zijn documents:read, documents:write, jobs:read, jobs:write, usage:read en webhooks:manage.
• Draai sleutels via Account en bewaar ze nooit in clientcode.

Bestanden

Upload met POST /api/v1/files als multipartveld file. De respons bevat een file_id. Vraag metadata op met GET /api/v1/files/:id en verwijder met DELETE /api/v1/files/:id. Bestanden zijn strikt gescheiden per account en modus.

Taken en bewerkingen

Maak een asynchrone taak met POST /api/v1/jobs, een ongewijzigde technische operation, invoerbestand-ID's en opties. Controleer GET /api/v1/jobs/:id totdat de status succeeded, failed of cancelled is en download via het geretourneerde resultaatendpoint.

Ondersteunde operation-identifiers: ocr searchable_pdf convert compress merge split rotate reorder delete_pages protect unlock redact.

Idempotentie

Stuur bij muterende verzoeken een unieke Idempotency-Key. Een herhaling met dezelfde body retourneert dezelfde respons; dezelfde sleutel met andere invoer geeft 409 idempotency_conflict.

POST /api/v1/jobs
Idempotency-Key: order-42-ocr        # ≤ 255 chars, scoped to the API key, kept 24h

# first call  → 202 + job
# retry       → 202 + the *same* job, header Idempotent-Replayed: true
# same key, different body → 422 idempotency_key_reused
# key still in flight      → 409 idempotency_in_progress

Webhooks

Registreer een HTTPS-endpoint om taakstatussen te ontvangen. Beschikbare events: job.succeeded job.failed job.cancelled file.expired webhook.test. Verifieer altijd de HMAC-handtekening op de ongewijzigde requestbytes en voorkom replay met tijdstempel en event-ID.

POST https://example.com/docaxo
Docaxo-Event: job.succeeded
Docaxo-Signature: t=1757700000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Content-Type: application/json

{
  "id": "evt_01J7…",
  "object": "event",
  "type": "job.succeeded",
  "api_version": "2026-09-01",
  "livemode": true,
  "created_at": "2026-09-12T18:00:00+00:00",
  "data": {
    "object": {
      "id": "…", "object": "job", "operation": "ocr", "status": "succeeded",
      "metadata": { "order": "42" },
      "result": { "download_url": "https://docaxo.com/api/v1/jobs/…/result", "pages_processed": 3 }
    }
  }
}

Handtekening verifiëren

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyDocaxoSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; // replay window
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

// Express: app.post("/docaxo", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyDocaxoSignature(req.body.toString("utf8"), req.get("Docaxo-Signature"), process.env.WHSEC)) return res.sendStatus(400);
//   const event = JSON.parse(req.body); … ; res.sendStatus(200);
// });

Nieuwe pogingen

Een niet-succesvolle 2xx-respons wordt opnieuw geprobeerd volgens 1m → 5m → 30m → 2h → 12h. Verwerking aan jouw kant moet daarom idempotent zijn.

Rate limits

Limieten gelden per API-sleutel en abonnement. De responsheaders tonen limiet, resterend aantal en resetmoment. Bij overschrijding volgt 429 rate_limited met Retry-After.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3

{"error":{"type":"rate_limit_error","code":"rate_limited",…}}

Fouten

Fouten hebben een stabiele JSON-envelope met machineleesbare error.code, een bericht, request-ID en optionele details. Vertaal alleen het bericht in je UI; programmeer tegen de identifier.

• 401 authentication_required — Geen Bearer-API-sleutel meegestuurd; cookies worden hier niet geaccepteerd.
• 401 invalid_api_key — Onbekende, ingetrokken of verlopen sleutel.
• 403 plan_required — Live-sleutels vereisen API Starter; upgrade_url verwijst naar checkout.
• 403 insufficient_scope — De sleutel mist de scope die dit endpoint vereist.
• 403 mode_mismatch — Het object hoort bij de andere modus (live ↔ test).
• 422 validation_error — Ongeldige body of parameters; param noemt het betrokken veld.
• 422 operation_unsupported — Voor deze bewerking of dit doel bestaat geen echte workerhandler.
• 422 invalid_options — Opties zijn ongeldig voor de gekozen bewerking.
• 415 unsupported_file_type — Content-type wordt niet geaccepteerd of past niet bij de bytes.
• 413 file_too_large — De upload overschrijdt de maximale grootte.
• 409 file_not_ready — De vooraf ondertekende upload is nog niet afgerond.
• 422 page_limit_exceeded — De taak bevat meer pagina's dan het abonnement toestaat.
• 402 insufficient_credits — Onvoldoende credits en meerverbruik is niet beschikbaar.
• 402 spending_cap_reached — De taak zou de bestedingslimiet overschrijden.
• 429 concurrency_limit — Te veel taken in wachtrij of uitvoering; probeer opnieuw nadat er een is afgerond.
• 429 rate_limited — De tokenbucket is leeg; respecteer Retry-After.
• 422 idempotency_key_reused — Dezelfde Idempotency-Key is met een andere requestbody gebruikt.
• 409 idempotency_in_progress — Het oorspronkelijke verzoek met deze sleutel wordt nog verwerkt.
• 404 not_found — Geen bestand, taak of webhook voor dit account en deze modus gevonden.
• 409 job_not_finished — Het resultaat is opgevraagd voordat de taak was voltooid.
• 409 no_downloadable_result — De taak heeft geen downloadbare uitvoer opgeleverd.
• 404 result_expired — Het resultaatobject is na de bewaartermijn verwijderd.
• 501 presigned_unavailable — Vooraf ondertekende URL's vereisen de S3-store; gebruik multipartupload.
• 502 webhook_delivery_failed — Je endpoint heeft het testevent geweigerd.
• 503 queue_unavailable — De taakwachtrij is onbereikbaar; opnieuw proberen met dezelfde Idempotency-Key is veilig.
• 500 internal_error — Fout aan onze kant; vermeld request_id bij een melding.

Prijzen en credits

API Starter kost €19/month per maand inclusief 2.000 credits. Extra gebruik kost €0.015 per credit. Normale documentpagina's kosten één credit; OCR kost 3 credits per pagina. Stel een bestedingslimiet in via Facturering.

Sandbox en live

dxk_test_-sleutels maken afzonderlijke sandboxbestanden, taken en webhooks en brengen niets in rekening. Resultaten zijn deterministische testuitvoer. dxk_live_-sleutels verwerken echte documenten. Objecten kunnen nooit tussen beide modi worden gelezen.

Endpointreferentie

Statische lijst — de live specificatie staat op https://docaxo.com/api/v1/openapi.json en Swagger UI op https://docaxo.com/api/v1/docs.