Documentvalidatie: API, Webhooks en ERP

Documentvalidatie mag nooit als een geisoleerde silo opereren. Wanneer een medewerker handmatig bestanden uploadt naar een losstaande tool, resultaten kopieert naar een CRM en vervolgens een ERP bijwerkt, introduceert elke stap vertraging, foutrisico en onderbroken audittrails. Voor organisaties die honderden dossiers per maand verwerken, wordt deze handmatige workflow een oprecht knelpunt.

Dit artikel beschrijft drie integratiepatronen die CheckFile rechtstreeks verbinden met uw informatiesysteem -- of dat nu Salesforce, SAP, een eigen CRM of een interne workflow-engine is. U vindt architectuurdiagrammen, werkende codevoorbeelden en best practices ontleend aan werkelijke implementaties. Zoekt u eerst de endpointreferentie, zie dan de API-gids.

Waarom Documentvalidatie Geen Losstaande Tool Mag Blijven

Een geïsoleerde validatietool introduceert drie structurele problemen: workflowverstoring (25–40 verloren uren per maand bij 500 dossiers), onderbroken audittrails en handmatige overschrijffouten (2–5% foutpercentage).

Wwft Art. 33 verplicht meldingsplichtige instellingen een onveranderlijk, tijdgestempeld auditlog van verificatiebeslissingen bij te houden gedurende minimaal vijf jaar; directe ERP-integratie via webhooks is de enige manier om deze traceerbaarheidsverplichting zonder handmatige tussenstap te borgen.

Een validatietool die buiten uw kernsystemen leeft creert drie structurele problemen.

Workflowverstoring. De medewerker verlaat zijn primaire omgeving (CRM, ERP, intern portaal) om een aparte tool te gebruiken. Elke heen-en-weerbeweging kost 2 tot 5 minuten per dossier. Bij 500 dossiers per maand telt dat op tot 25 tot 40 verloren uren.

Onderbroken audittrails. Validatieresultaten zijn niet gekoppeld aan het clientrecord in het referentiesysteem. Tijdens een audit moet de keten handmatig worden gereconstrueerd.

Overschrijffouten. Wanneer een medewerker handmatig een documentstatus kopieert van de validator naar het CRM, ligt het foutpercentage tussen 2 en 5 procent. Bij 10.000 dossiers per jaar betekent dat 200 tot 500 records met inconsistente status.

Directe integratie elimineert alle drie. De rest van dit artikel legt uit hoe dit te implementeren.

Drie Integratiepatronen

Drie patronen dekken de meeste integratiescenario's: batch-upload (lage complexiteit, minuten tot uren latency), realtime API (2–15 seconden, voor interactieve onboarding) en event-driven webhooks (vrijwel directe push, aanbevolen voor ERP-integraties).

De AMLD6 (Richtlijn (EU) 2024/1640) verplicht meldingsplichtige instellingen continue monitoring van zakelijke relaties; event-driven webhooks die ERP-records automatisch bijwerken bij documentwijzigingen zijn de technologische implementatie van deze doorlopende zorgplicht.

Het juiste patroon hangt af van documentvolume, acceptabele latency en de technische volwassenheid van uw team.

Patroon 1 -- Batch-upload

Batch-upload past wanneer latency niet kritiek is: migratie van een documentarchief, periodieke herverwerking of nachtelijke datawarehouse-feeds.

# Upload een batch van 3 documenten
curl -X POST https://api.checkfile.ai/api/v1/files/batch \
  -H "X-API-Key: ck_live_your_key" \
  -F "files[]=@factuur_001.pdf" \
  -F "files[]=@kvk_uittreksel.pdf" \
  -F "files[]=@bankgegevens.pdf" \
  -F "dossier_id=DOS-2026-0042" \
  -F "callback_url=https://your-app.com/webhooks/checkfile"

Patroon 2 -- Realtime API

Dit is het meest voorkomende patroon voor interactieve applicaties: een gebruiker uploadt een document, uw applicatie verzendt het naar CheckFile, wacht op het resultaat en toont het.

# Upload een enkel document
curl -X POST https://api.checkfile.ai/api/v1/files \
  -H "X-API-Key: ck_live_your_key" \
  -H "Idempotency-Key: upload-dos042-kvk" \
  -F "file=@kvk_uittreksel.pdf" \
  -F "document_type=company_registration" \
  -F "rules=freshness_90d,company_number_match"

Patroon 3 -- Event-driven webhooks

Webhooks keren de stroom om: in plaats van de API te pollen, meldt CheckFile uw systeem zodra verwerking is voltooid. Dit is het aanbevolen patroon voor geautomatiseerde pipelines en ERP-integraties.

Webhook-architectuur in Detail

Registreren van een webhook-endpoint

curl -X POST https://api.checkfile.ai/api/v1/webhooks \
  -H "X-API-Key: ck_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/checkfile",
    "events": ["file.validated", "file.rejected", "batch.completed"],
    "secret": "whsec_your_signing_secret"
  }'

Webhook-payload: document gevalideerd

{
  "event": "file.validated",
  "timestamp": "2026-02-21T14:22:18Z",
  "data": {
    "file_id": "fil_8b2c4d1e",
    "dossier_id": "DOS-2026-0042",
    "document_type": "company_registration",
    "status": "validated",
    "confidence_score": 0.97,
    "extracted_fields": {
      "company_name": "ACME Industrie B.V.",
      "company_number": "12345678",
      "incorporation_date": "2019-03-15",
      "registered_address": "Keizersgracht 42, 1015 CS Amsterdam",
      "director": "Jan de Vries",
      "document_date": "2026-01-28"
    },
    "rules_results": [
      {
        "rule": "freshness_90d",
        "status": "passed",
        "detail": "Document gedateerd 28-01-2026, geldig tot 28-04-2026"
      },
      {
        "rule": "company_number_match",
        "status": "passed",
        "detail": "KVK-nummer 12345678 komt overeen met dossierrecord"
      }
    ]
  }
}

Webhook afhandelen in Python

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

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

@app.route("/webhooks/checkfile", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-CheckFile-Signature", "")
    if not verify_signature(request.data, signature):
        abort(401)

    event = request.json
    event_type = event["event"]
    data = event["data"]

    if event_type == "file.validated":
        update_crm_document_status(
            dossier_id=data["dossier_id"],
            document_type=data["document_type"],
            status="validated",
            extracted_fields=data["extracted_fields"]
        )
    elif event_type == "file.rejected":
        trigger_operator_alert(
            dossier_id=data["dossier_id"],
            reasons=data["rejection_reasons"]
        )

    return {"received": True}, 200

ERP-integratiepatronen per Platform

Salesforce

De meest voorkomende Salesforce-integratie gebruikt een Apex Trigger of Flow getriggerd door de CheckFile-webhook. Typische architectuur: lichtgewicht middleware (Heroku, AWS Lambda of MuleSoft) ontvangt de webhook, roept de Salesforce REST API aan om het Document__c-object bij te werken, en een Salesforce Flow triggert downstream bedrijfslogica.

SAP

Voor SAP S/4HANA of SAP Business One bestaan twee benaderingen: via SAP Integration Suite (voorheen CPI) met een iFlow, of via generieke middleware (Python of Node.js-connector die de SAP OData API rechtstreeks aanroept).

Eigen CRM of Interne Tool

Voor interne tools is de webhook de meest directe methode. Uw backend ontvangt de payload, extraheert relevante velden en werkt uw database bij. Geen aanvullende middleware nodig.

Authenticatie en Beveiliging

API-sleutels worden per omgeving afgebakend (test: ck_test_, productie: ck_live_), rotatie elke 90 dagen is verplicht, en opslag uitsluitend via geheimenbeheer zoals HashiCorp Vault of AWS Secrets Manager -- nooit als platte tekst in broncode.

De Autoriteit Persoonsgegevens stelt dat verwerkers van identiteitsdocumenten onder AVG Art. 32 verplicht zijn passende technische beveiligingsmaatregelen te implementeren, waaronder encryptie in transit (TLS 1.3) en at rest (AES-256) -- vereisten waaraan de CheckFile API-infrastructuur standaard voldoet.

API-key best practices

• Een sleutel per omgeving. Ontwikkeling (ck_test_), staging, productie (ck_live_). Deel nooit een sleutel over omgevingen.
• Regelmatige rotatie. Roteer sleutels elke 90 dagen. De API ondersteunt twee actieve sleutels gelijktijdig voor downtime-vrije rotatie.
• Veilige opslag. Gebruik Vault (HashiCorp), AWS Secrets Manager of Azure Key Vault. Sla sleutels nooit op in platte tekst in broncode.

Webhookverificatie

Elke webhook is ondertekend met uw geheim (whsec_...). Verifieer altijd de HMAC-SHA256-handtekening alvorens de payload te verwerken.

Foutafhandeling en Retry-strategieen

Transiënte fouten (5xx, timeout)

CheckFile herhaalt webhooks automatisch bij falen. Het retryschema volgt exponential backoff:

Idempotentie

Uw webhook-endpoint moet idempotent zijn. CheckFile kan dezelfde gebeurtenis opnieuw verzenden bij een netwerktimeout. Gebruik het file_id-veld als idempotentiesleutel.

Migratiepad: Van Handmatige Upload naar Volledig Geautomatiseerde Pipeline

Fase 1 -- Webinterface (week 1). Gebruik het CheckFiledashboard om uw eerste documenten handmatig te valideren. Doel: bedrijfsregels en documenttypen bevestigen.

Fase 2 -- Realtime API (weken 2-3). Integreer de upload-API in uw applicatie. Medewerkers verlaten hun primaire tool niet meer, maar het proces wordt nog handmatig geinitieerd.

Fase 3 -- Webhooks (weken 4-5). Activeer webhooks om resultaten automatisch te ontvangen. Uw CRM/ERP wordt bijgewerkt zonder menselijke tussenkomst.

Fase 4 -- Volledig geautomatiseerde pipeline (weken 6-8). Documenten worden automatisch geuploaded bij ontvangst (e-mailparser, klantportaal, scanner). Webhooks voeden het ERP. Medewerkers behandelen alleen uitzonderingen.

Bij elke fase kunt u tijdsbesparing en foutreductiemeten om de investering in de volgende stap te rechtvaardigen. Als u overweegt of u uw eigen validatieoplossing moet bouwen of een bestaand platform moet gebruiken, lees dan onze bouwen of kopen-analyse.

Conclusie: Integratie als Productiviteitsmultiplicator

Documentvalidatie levert zijn volledige waarde pas wanneer het is verweven in de bestaande workflow. Een goed ontworpen REST API, betrouwbare webhooks en integratiepatronen afgestemd op uw ERP transformeren een verificatietool in een natieve component van uw informatiesysteem.

De concrete winst: eliminatie van handmatige overschrijving, volledige audittrails, realtimeverwerking en meetbare foutreductiereductie. Voor teams die meer dan 200 dossiers per maand verwerken, levert integratie doorgaans rendement op investering op in minder dan 3 maanden.

Klaar om documentvalidatie te verbinden met uw IT-systeem? Verken de CheckFile API-documentatie of neem contact op met ons technisch team voor begeleiding op maat. Prijzen inclusief API-toegang op alle plannen, met een sandbox-omgeving om uw integratie te testen voor livegang.

Veelgestelde Vragen

Wat is het verschil tussen de realtime API en event-driven webhooks voor documentvalidatie?

Bij de realtime API uploadt uw applicatie een document, wacht op het resultaat (2-15 seconden) en toont dit aan de gebruiker, wat geschikt is voor interactieve onboarding. Webhooks keren de stroom om: CheckFile meldt uw systeem proactief zodra verwerking is voltooid, zonder polling. Dit is het aanbevolen patroon voor geautomatiseerde pipelines en ERP-integraties waarbij latency minder kritiek is maar betrouwbare, asynchroon afgeleverde resultaten essentieel zijn.

Hoe integreer ik documentvalidatieresultaten in Salesforce?

De meest gangbare aanpak gebruikt een Apex Trigger of Salesforce Flow getriggerd door de CheckFile-webhook. Een lichtgewicht middleware (Heroku, AWS Lambda of MuleSoft) ontvangt de webhook-payload, roept de Salesforce REST API aan om het relevante object bij te werken, en een Flow triggert vervolgens downstream bedrijfslogica zoals het aanmaken van taken of het bijwerken van dossierstatus. De webhookpayload bevat geëxtraheerde velden en validatieresultaten die direct in Salesforce-velden kunnen worden gemapt.

Hoe lang duurt het om documentvalidatie volledig te automatiseren in een bestaande pipeline?

Een gefaseerd migratiepad van handmatige upload naar volledig geautomatiseerde pipeline verloopt in vier fasen van elk één tot twee weken. Fase 1 is handmatig gebruik van het dashboard voor bevestiging van documenttypen en regels. Fase 2 integreert de upload-API zodat medewerkers hun primaire tool niet verlaten. Fase 3 activeert webhooks voor automatische resultaatverwerking. Fase 4 automatiseert de documentinvoer via e-mailparser of klantportaal. Totale implementatietijd: zes tot acht weken.

Hoe beveilig ik API-sleutels in een productieomgeving?

API-sleutels mogen nooit als platte tekst in broncode worden opgeslagen. Gebruik geheimenbeheertools zoals HashiCorp Vault, AWS Secrets Manager of Azure Key Vault. Gebruik één sleutel per omgeving (test, staging, productie) en roteer sleutels elke 90 dagen; de API ondersteunt twee actieve sleutels tegelijk voor downtime-vrije rotatie. Verifieer daarnaast altijd de HMAC-SHA256-handtekening van inkomende webhookpayloads om manipulatie te voorkomen.