BIQE API

Integreer handschriftherkenning met LLM-correctie direct in uw eigen pipeline. REST-gebaseerd, JSON-respons, authenticatie via API-sleutel.

De BIQE-API is bedoeld voor productiegebruik: u dient pagina's programmatisch in, volgt de status en haalt het resultaat op — zonder het portaal te openen. De verwerking is dezelfde keten als in het portaal (layout-detectie, herkenning, LLM-correctie, export naar PageXML/ALTO/PDF).

Authenticatie

Elke request authenticeert met een API-sleutel. U kunt de sleutel meegeven via de X-API-Key-header, of via een Authorization: Bearer-header — beide worden geaccepteerd. Verkeer loopt over versleutelde HTTPS.

X-API-Key: biqe_live_xxxxxxxxxxxxxxxxxxxxxxxx

# of, gelijkwaardig:
Authorization: Bearer biqe_live_xxxxxxxxxxxxxxxxxxxxxxxx

API-sleutels beheren

Sleutels maakt en beheert u zelf in het klantportaal onder Instellingen ▸ API-sleutels ▸ + Nieuwe API-sleutel. Geef de sleutel een label. De waarde wordt eenmalig getoond bij het aanmaken — daarna kan hij niet opnieuw worden weergegeven. Intrekken kan op dezelfde pagina en werkt direct.

Een scan indienen

Dien pagina's in als ZIP-archief (één afbeelding per pagina), als multipart-veld scan_zip. Geef optioneel een verwerkingsniveau, preset en webhook-URL mee.

curl -X POST https://ocr-handwriting.online/v1/process-scan \
  -H "X-API-Key: $BIQE_API_KEY" \
  -F "scan_zip=@my-pages.zip" \
  -F "llm_tier=balanced" \
  -F "preset=generic_historical" \
  -F "webhook_url=https://your-system.example/biqe-callback"

Respons — 202 Accepted:

{
  "job_id": "ff6f3db8-ab61-47d0-9f69-1987b5b0f2f0",
  "state": "queued",
  "page_count": 14,
  "created_at": "2026-05-02T11:56:05Z",
  "expires_at": "2026-05-09T11:56:05Z",
  "status_url": ".../v1/process-scan/ff6f3db8-...",
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

De taakstatus volgen

Pol de status, of wacht op de webhook-callback (aanbevolen voor grotere volumes).

curl https://ocr-handwriting.online/v1/process-scan/<job_id> \
  -H "X-API-Key: $BIQE_API_KEY"

Respons (velden afhankelijk van de voortgang):

{
  "job_id": "ff6f3db8-...",
  "state": "done",
  "page_count": 14,
  "current_step": "export",
  "created_at": "2026-05-02T11:56:05Z",
  "started_at": "2026-05-02T11:56:09Z",
  "finished_at": "2026-05-02T11:57:43Z",
  "expires_at": "2026-05-09T11:56:05Z",
  "error_message": null,
  "warning_message": null,
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

Het resultaat ophalen

Zodra de status done is, downloadt u via dit endpoint (of via de result_url) het resultaat-archief: PageXML, ALTO en — indien aangezet — een doorzoekbare PDF. De link blijft ongeveer 7 dagen beschikbaar (zie expires_at).

curl -L https://ocr-handwriting.online/v1/process-scan/<job_id>/result \
  -H "X-API-Key: $BIQE_API_KEY" \
  -o result.zip

Een taak annuleren

Een taak die nog in de wachtrij staat of wordt verwerkt, kunt u annuleren. De status gaat dan naar cancelled.

curl -X DELETE https://ocr-handwriting.online/v1/process-scan/<job_id> \
  -H "X-API-Key: $BIQE_API_KEY"

Webhook-callback & retries

Geeft u een webhook_url mee, dan sturen wij een POST met JSON zodra de taak een eindtoestand bereikt (done of failed). De callback bevat deze headers:

De payload:

{
  "job_id": "ff6f3db8-...",
  "state": "done",
  "page_count": 14,
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

result_url is alleen aanwezig wanneer state gelijk is aan done. Mislukte afleveringen proberen we tot vijf keer opnieuw met exponentiële back-off (ongeveer 1, 5, 25, 125 en 625 seconden). Uw endpoint moet zo snel mogelijk een 2xx teruggeven en bereikbaar zijn over HTTPS.

De webhook-handtekening verifiëren

Elke callback is ondertekend. De handtekening is een HMAC-SHA256 over de ruwe request-body, met uw per-account webhook-secret als sleutel, als lowercase hex in de header X-BIQE-Signature. Het secret (64 hex-tekens) is per klant; u vraagt het op via het portaal.

import hmac, hashlib

secret = "<your-webhook-secret>".encode()
body   = request.get_data()  # raw bytes
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, request.headers["X-BIQE-Signature"]):
    return "forbidden", 403

Taakstatussen

Parameters van process-scan

Foutafhandeling