Documentvalidatie API: Ontwikkelaarsgids

Deze gids behandelt alles wat u nodig hebt om geautomatiseerde documentvalidatie te integreren in uw applicatie -- van authenticatie tot webhookafhandeling. Of u nu een clientonboardingflow, een compliancepipeline of een backoffice-automatiseringstool bouwt, de CheckFile API geeft u programmatische toegang tot dezelfde AI-aangedreven validatie-engine die in het platform wordt gebruikt. U vindt architectuurbeslissingen, endpointreferenties, codevoorbeelden in Python en Node.js, webhookpayloads, foutafhandelingsstrategieen en integratiepatronen die schalen van prototype naar productie.

Architectuuroverzicht

De CheckFile API volgt een standaard asynchroon verwerkingsmodel: documenten worden via REST geüpload, in wachtrij geplaatst voor AI-analyse, en resultaten geleverd via polling (2–15 seconden) of webhookcallbacks.

AVG Art. 25 (Privacy by Design) en Art. 32 (beveiliging van verwerking) verplichten organisaties die persoonsgegevens in documenten verwerken tot technische waarborgen zoals end-to-end TLS-versleuteling en minimale bewaartermijnen -- eisen waaraan de CheckFile API voldoet conform de richtlijnen van de Autoriteit Persoonsgegevens. Documenten worden geuploaded via REST, in de wachtrij geplaatst voor AI-analyse, en resultaten worden geleverd via polling of webhookcallbacks. Deze ontkoppelde architectuur laat het systeem documenten op schaal verwerken zonder uw applicatie te blokkeren.

                                    +-------------------+
                                    |  Results API      |
                                    |  GET /files/{id}  |
                                    +--------^----------+
                                             |
Client App                                   | Poll of ophalen
    |                                        |
    |  POST /v1/files                +-------+--------+
    +------------------------------->| Upload API     |
    |                                +-------+--------+
    |                                        |
    |                                        v
    |                               +--------+--------+
    |                               | Verwerkingswacht-|
    |                               | rij (AI-valida-  |
    |                               | tie)             |
    |                               +--------+--------+
    |                                        |
    |         Webhook callback               |
    |<---------------------------------------+
    |         POST uw-endpoint

Drie kernbeslissingen vormen deze architectuur:

1. Standaard asynchroon. Documentvalidatie omvat OCR, fraudedetectie, kruisverwijzing en regelevaluatie. Deze bewerkingen duren 2-15 seconden afhankelijk van documentcomplexiteit. De API accepteert uploads onmiddellijk en verwerkt ze op de achtergrond.

2. Dubbele levering. U kunt het statusendpoint pollen of een webhook registreren. Polling werkt voor eenvoudige integraties; webhooks zijn de aanbevolen aanpak voor productiesystemen die meer dan een paar documenten per minuut verwerken.

3. Idempotente uploads. Elke upload retourneert een uniek file_id. Het opnieuw uploaden van hetzelfde document met dezelfde idempotentiesleutel retourneert het bestaande resultaat in plaats van opnieuw te verwerken, wat zowel tijd als API-credits bespaart.

Authenticatie en Beveiliging

Alle API-verzoeken vereisen Bearer-authenticatie via een API-sleutel (server-naar-server) of OAuth 2.0 authorization code flow (gebruikersgebonden toegang) -- beide methoden versleutelen verkeer via TLS 1.3.

De AMLD6-richtlijn (EU) 2024/1640 vereist dat meldingsplichtige instellingen een auditeerbare verwerkingsketen onderhouden voor alle KYC-verificaties; API-integratie met gestructureerde webhookpayloads en gedateerde verwerkingsresultaten voldoet aan deze traceerbaarheidsverplichting.

Alle API-verzoeken vereisen authenticatie. De API ondersteunt twee authenticatiemethoden afhankelijk van uw toepassing.

API-sleutelauthenticatie

Voor server-naar-serverintegraties, geef uw API-sleutel door in de X-API-Key header:

curl -H "X-API-Key: ck_live_abc123..." \
     https://api.checkfile.ai/v1/files

API-sleutels zijn afgebakend tot uw organisatie. U kunt meerdere sleutels genereren in het dashboard -- een per omgeving (ontwikkeling, staging, productie) is de aanbevolen praktijk. Sleutels met prefix ck_test_ gebruiken de sandbox-omgeving; sleutels met prefix ck_live_ gebruiken productie.

OAuth 2.0 voor Gebruikersgebonden Toegang

Als uw applicatie namens eindgebruikers handelt (bijv. een multi-tenant SaaS), gebruik OAuth 2.0 met de authorization code flow. Dit biedt audittrails op gebruikersniveau en granulaire toestemmingsafbakening.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://uwapp.nl/callback

Toegangstokens verlopen na 1 uur. Gebruik het verversingstoken om nieuwe toegangstokens te verkrijgen zonder opnieuw te authenticeren.

Tarieflimieten

Tarieflimieten worden per API-sleutel afgedwongen, gemeten in verzoeken per minuut:

Wanneer u de tarieflimiet overschrijdt, retourneert de API 429 Too Many Requests met een Retry-After header die aangeeft hoeveel seconden te wachten. Zie prijzen voor plandetails.

Transportbeveiliging

Al het verkeer is versleuteld met TLS 1.3. De API weigert verbindingen via TLS 1.2 of eerder. Certificate pinning is beschikbaar voor Enterprise-klanten. Alle geuploadde documenten worden at rest versleuteld met AES-256 en automatisch gewist na de bewaarperiode geconfigureerd in uw accountinstellingen. Lees meer over onze beveiligingspraktijken.

Kernendpoints

De API biedt zes primaire endpoints voor upload (enkelvoudig en batch), statuscontrole, resultaatophaling, regelconfiguratie en webhookbeheer -- alle bereikbaar via https://api.checkfile.ai/v1.

De De Nederlandsche Bank (DNB) verwacht dat financiële instellingen verificatieresultaten minstens vijf jaar bewaren (Wwft Art. 33); de CheckFile API levert tijdgestempelde auditlogs die direct voldoen aan deze bewaarverplichting.

De API is georganiseerd rond zes primaire endpoints:

Alle endpoints accepteren en retourneren JSON (behalve bestandsuploadendpoints, die multipart/form-data accepteren). De basis-URL is https://api.checkfile.ai. API-versiebeheer is padgebaseerd; de huidige stabiele versie is v1.

Uploaden en Valideren -- Stap voor Stap

De meest voorkomende workflow is: documenten uploaden, wachten op verwerking, resultaten ophalen. Hier is de volledige flow in zowel Python als Node.js.

Python (requests)

import requests
import time

API_KEY = "ck_live_abc123..."
BASE_URL = "https://api.checkfile.ai/v1"
HEADERS = {"X-API-Key": API_KEY}

# Stap 1: Upload een batch documenten als dossier
response = requests.post(
    f"{BASE_URL}/files/batch",
    headers=HEADERS,
    files=[
        ("files", ("contract.pdf", open("contract.pdf", "rb"), "application/pdf")),
        ("files", ("overeenkomst.pdf", open("overeenkomst.pdf", "rb"), "application/pdf")),
        ("files", ("kvk_uittreksel.pdf", open("kvk_uittreksel.pdf", "rb"), "application/pdf")),
    ],
    data={"rule_set": "equipment-leasing"}
)
response.raise_for_status()
file_id = response.json()["id"]
print(f"Dossier geuploaded: {file_id}")

# Stap 2: Poll voor voltooiing
while True:
    status_resp = requests.get(
        f"{BASE_URL}/files/{file_id}/status",
        headers=HEADERS
    )
    status = status_resp.json()["status"]
    if status in ("completed", "failed"):
        break
    time.sleep(2)  # Poll elke 2 seconden

# Stap 3: Haal resultaten op
results = requests.get(
    f"{BASE_URL}/files/{file_id}/results",
    headers=HEADERS
).json()

for doc in results["documents"]:
    print(f"{doc['filename']}: {doc['verdict']} (betrouwbaarheid: {doc['confidence']})")
    if doc["alerts"]:
        for alert in doc["alerts"]:
            print(f"  - {alert['severity']}: {alert['message']}")

Node.js (fetch + FormData)

import fs from 'node:fs';

const API_KEY = process.env.CHECKFILE_API_KEY;
const BASE_URL = 'https://api.checkfile.ai/v1';

// Stap 1: Upload een batch documenten
const form = new FormData();
form.append('files', new Blob([fs.readFileSync('contract.pdf')]), 'contract.pdf');
form.append('files', new Blob([fs.readFileSync('overeenkomst.pdf')]), 'overeenkomst.pdf');
form.append('files', new Blob([fs.readFileSync('kvk_uittreksel.pdf')]), 'kvk_uittreksel.pdf');
form.append('rule_set', 'equipment-leasing');

const uploadRes = await fetch(`${BASE_URL}/files/batch`, {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY },
  body: form,
});
const { id: fileId } = await uploadRes.json();
console.log(`Dossier geuploaded: ${fileId}`);

// Stap 2: Poll voor voltooiing
let status = 'processing';
while (status !== 'completed' && status !== 'failed') {
  await new Promise((r) => setTimeout(r, 2000));
  const statusRes = await fetch(`${BASE_URL}/files/${fileId}/status`, {
    headers: { 'X-API-Key': API_KEY },
  });
  ({ status } = await statusRes.json());
}

// Stap 3: Haal resultaten op
const results = await fetch(`${BASE_URL}/files/${fileId}/results`, {
  headers: { 'X-API-Key': API_KEY },
}).then((r) => r.json());

for (const doc of results.documents) {
  console.log(`${doc.filename}: ${doc.verdict} (betrouwbaarheid: ${doc.confidence})`);
  for (const alert of doc.alerts) {
    console.log(`  - ${alert.severity}: ${alert.message}`);
  }
}

Beide voorbeelden volgen hetzelfde driestapenpatroon: uploaden, pollen, ophalen. Vervang voor productiesystemen de pollingloop door een webhooklistener (behandeld in de volgende sectie).

Webhookpayloads

Webhooks elimineren de noodzaak van polling. Registreer een webhook-URL in het dashboard of via de API, en CheckFile zal een ondertekende JSON-payload POSTen naar uw endpoint wanneer verwerking is voltooid of een waarschuwing is gedetecteerd.

Validatie Voltooid Evenement

{
  "event": "validation.completed",
  "timestamp": "2026-02-09T14:32:08Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "rule_set": "equipment-leasing",
    "verdict": "approved",
    "processing_time_ms": 4280,
    "documents": [
      {
        "filename": "contract.pdf",
        "type": "contract",
        "verdict": "valid",
        "confidence": 0.97,
        "alerts": []
      },
      {
        "filename": "overeenkomst.pdf",
        "type": "agreement",
        "verdict": "valid",
        "confidence": 0.95,
        "alerts": []
      },
      {
        "filename": "kvk_uittreksel.pdf",
        "type": "company_registration",
        "verdict": "valid",
        "confidence": 0.99,
        "alerts": []
      }
    ]
  }
}

Waarschuwing Gedetecteerd Evenement

Wanneer de AI een potentieel probleem detecteert tijdens validatie, wordt direct een waarschuwingsevenement gegenereerd -- voor de volledige validatie is voltooid. Dit laat uw applicatie reageren op ernstige problemen in realtime.

{
  "event": "validation.alert",
  "timestamp": "2026-02-09T14:32:06Z",
  "data": {
    "file_id": "dossier_8f3a2b1c",
    "document": {
      "filename": "kvk_uittreksel.pdf",
      "type": "company_registration"
    },
    "alert": {
      "code": "DOC_EXPIRED",
      "severity": "high",
      "message": "KVK-uittreksel verlopen op 30-11-2025",
      "field": "validity_date",
      "extracted_value": "2025-11-30",
      "expected": "Document moet minder dan 3 maanden oud zijn"
    }
  }
}

Webhookhandtekeningen Verifieren

Elk webhookverzoek bevat een X-Checkfile-Signature header met een HMAC-SHA256-handtekening. Verifieer deze tegen uw webhookgeheim om te waarborgen dat de payload niet is gemanipuleerd:

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Best Practices voor Foutafhandeling

De API gebruikt standaard HTTP-statuscodes. Hier zijn de meest voorkomende fouten en hoe ermee om te gaan:

Retry-Strategie met Exponential Backoff

Voor tijdelijke fouten (429, 500, 502, 503), implementeer exponential backoff met jitter:

import time
import random
import requests

def api_request_with_retry(method, url, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(method, url, **kwargs)

        if response.status_code < 400:
            return response

        if response.status_code in (429, 500, 502, 503):
            base_delay = min(2 ** attempt, 60)  # Maximum 60 seconden
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            if response.status_code == 429:
                retry_after = response.headers.get("Retry-After")
                if retry_after:
                    delay = float(retry_after)

            time.sleep(delay)
            continue

        # Niet-herhaalbare fout
        response.raise_for_status()

    raise Exception(f"Maximum pogingen overschreden voor {url}")

Kernprincipes: probeer nooit 400-niveau clientfouten opnieuw (behalve 429), respecteer altijd de Retry-After header, en voeg jitter toe om thundering herd-problemen te voorkomen wanneer meerdere clients gelijktijdig opnieuw proberen.

Integratiepatronen

Drie patronen dekken het merendeel van integratiescenario's. Kies het patroon dat past bij uw latency- en doorvoerivereisten.

Patroon 1: Realtimevalidatie (Upload, Poll, Toon)

Geschikt voor: gebruikersgerichte flows waar de eindgebruiker op resultaten wacht (bijv. onboardingformulieren).

Typische latency: 3-8 seconden voor een enkel document. Toon een voortgangsindicator aan de gebruiker. Als verwerking 15 seconden overschrijdt, toon een bericht en bied aan via e-mail te notificeren.

Patroon 2: Batchverwerking (Upload Batch, Webhooknotificatie)

Geschikt voor: backoffice-workflows die grote volumes verwerken (bijv. nachtelijke imports, bulk-onboarding).

Dit patroon ontkoppelt indiening volledig van verwerking. Uw systeem verzendt en vergeet, reageert vervolgens op webhookgebeurtenissen. Voor zeer grote batches (1.000+ dossiers), spreid uploads op 50 per minuut om binnen tarieflimieten te blijven.

Patroon 3: CRM-integratie (Salesforce, HubSpot, Custom)

Geschikt voor: teams die clientdossiers beheren in een CRM en validatiestatus automatisch willen synchroniseren.

De middlewarelaag (een lichtgewicht serverless-functie of integratieplatform zoals Zapier/Make) vertaalt tussen de CheckFile API en het datamodel van uw CRM. Veelvoorkomende CRM-veldmappings:

Prestatiebenchmarks

Verwerkingstijden hangen af van documentaantal, complexiteit en de toegepaste regelset. De volgende benchmarks zijn gemeten op productie-infrastructuur onder typische belasting:

Deze tijden weerspiegelen end-to-end verwerking inclusief OCR, AI-analyse, kruisverwijzing en regelevaluatie. Uploadtijd (netwerkoverdracht) is niet inbegrepen en hangt af van uw verbindingssnelheid en bestandsgroottes.

Aan de Slag

Het snelste pad van nul naar een werkende integratie:

1. Maak een account aan en genereer een test-API-sleutel (ck_test_ prefix) vanuit het dashboard.
2. Upload een testdocument met het curl-voorbeeld hierboven of de codevoorbeelden in deze gids.
3. Registreer een webhook om resultaten asynchroon te ontvangen.
4. Configureer een regelset die past bij uw bedrijfsvereisten.
5. Schakel over naar productie door uw testsleutel te vervangen door een live sleutel (ck_live_ prefix).

Volledige endpointdocumentatie, SDK's (Python, Node.js, Go) en een interactieve API-verkenner zijn beschikbaar op docs.checkfile.ai. Hebt u vragen over welk plan past bij uw volume, zie prijzen of neem rechtstreeks contact op met het engineeringteam.

Gerelateerde lectuur: Voor ERP-specifieke integratiepatronen inclusief Salesforce en SAP, zie onze API, webhooks en ERP-integratiegids. Als u overweegt of u validatie intern wilt bouwen of een API zoals deze wilt gebruiken, biedt onze bouwen of kopen-analyse een gedetailleerde 3-jaars kostenvergelijking.

Veelgestelde Vragen

Wat is het asynchrone verwerkingsmodel van de documentvalidatie-API?

Documenten worden via een POST-verzoek geüpload naar de API, in een verwerkingswachtrij geplaatst voor AI-analyse, en resultaten worden daarna geleverd via polling (GET-verzoek op het statusendpoint) of via een webhookcallback. Dit ontkoppelde model laat het systeem documenten op schaal verwerken zonder uw applicatie te blokkeren tijdens de 2 tot 15 seconden die OCR, fraudedetectie, kruisverwijzing en regelevaluatie in beslag nemen.

Welke authenticatiemethoden ondersteunt de API?

De API ondersteunt twee methoden. API-sleutelauthenticatie via de X-API-Key header is geschikt voor server-naar-serverintegraties. OAuth 2.0 met de authorization code flow is de aanbevolen aanpak voor multi-tenant SaaS-toepassingen waarbij uw applicatie namens eindgebruikers handelt. Beide methoden versleutelen verkeer via TLS 1.3. Toegangstokens bij OAuth verlopen na 1 uur en kunnen via een verversingstoken worden vernieuwd.

Hoe ga ik om met API-tarieflimieten bij het verwerken van grote batches?

Het Starter-plan staat 100 verzoeken per minuut toe, het Business-plan 500 per minuut. Voor grote batches van meer dan 1.000 dossiers spreidt u uploads op 50 per minuut om binnen tarieflimieten te blijven. Bij overschrijding retourneert de API een 429-statuscode met een Retry-After header. Implementeer exponential backoff met jitter voor 429- en 5xx-fouten, maar probeer 4xx-clientfouten nooit opnieuw behalve 429. De API ondersteunt idempotente uploads zodat een herpoging na een netwerktimeout geen duplicaten aanmaakt.

Hoe lang worden validatieresultaten bewaard en zijn ze auditeerbaar?

Validatieresultaten worden opgeslagen conform de bewaartermijn die u in uw accountinstellingen configureert. Elk resultaat is voorzien van een tijdstempel en bevat de volledige audittrail van het verificatieproces: welk document is verwerkt, welke regels zijn toegepast, welk resultaat per regel is geretourneerd en de algehele betrouwbaarheidsscore. Deze gestructureerde audittrail voldoet aan de Wwft-verplichting van minimaal 5 jaar bewaring van verificatiebeslissingen conform Artikel 33.