Een bemiddelaar met een betaald account haalt met een eigen sleutel op wat het tabblad Kandidaten toont. Het meldt de stand terug en ontvangt berichten van ZZPdock. Alles gaat over de eigen opdrachten van het bureau en alleen over zzp'ers die zelf hebben aangezet dat bureaus hen mogen benaderen. De beschrijving in OpenAPI 3.1 staat op https://zzpdock.nl/api/v1/bemiddelaar/openapi.json.

Sleutel

Lijsten

Elke lijst werkt hetzelfde en heeft dezelfde vorm.

{
  "gegevens": [],
  "volgende": null
}

Fouten

Elke fout heeft de passende HTTP-status en dezelfde vorm. De code is het contract en de melding mag veranderen.

{
  "fout": {
    "code": "geen_recht",
    "melding": "Deze sleutel mag geen contactgegevens lezen.",
    "veld": null,
    "verzoek_id": "vrz_k2m8qz4c7w1x9d3f5h6j"
  }
}

Adressen

Alles staat onder https://zzpdock.nl/api/v1/bemiddelaar. De voorbeelden gebruiken de ID's van de testgegevens (zie Testen) en werken met een testsleutel.

GET /sleutel

Wie ben ik: bureau plus rechten plus soort sleutel. Zonder sleutel.

curl "https://zzpdock.nl/api/v1/bemiddelaar/sleutel"
{
  "bureau": "Voorbeeld Interim",
  "sleutel_id": "sl_7h2k9m4p1q8r5t3v6w0x",
  "soort": "test",
  "rechten": [
    "kandidaten:lezen",
    "contact:lezen",
    "stand:schrijven"
  ],
  "toegang_tot": "2027-02-20T00:00:00Z"
}

GET /opdrachten

Eigen opdrachten met het aantal passende kandidaten. Recht: kandidaten:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "gegevens": [
    {
      "opdracht_id": "opd_test0000000000000001",
      "titel": "Voorbeeldopdracht projectmanager",
      "opdrachtgever": "Gemeente Voorbeeldstad",
      "plaats": "Voorbeeldstad",
      "uren_per_week": 32,
      "startdatum": "2027-01-04",
      "tarief_max": 100,
      "status": "open",
      "url": null,
      "bron": "zzpdock",
      "externe_referentie": null,
      "geplaatst_op": "2026-10-20T08:00:00Z",
      "gewijzigd_op": "2026-11-01T08:00:00Z",
      "passende_kandidaten": 3
    }
  ],
  "volgende": null
}

GET /opdrachten/{opdracht_id}

Eén opdracht. Recht: kandidaten:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "opdracht_id": "opd_test0000000000000001",
  "titel": "Voorbeeldopdracht projectmanager",
  "opdrachtgever": "Gemeente Voorbeeldstad",
  "plaats": "Voorbeeldstad",
  "uren_per_week": 32,
  "startdatum": "2027-01-04",
  "tarief_max": 100,
  "status": "open",
  "url": null,
  "bron": "zzpdock",
  "externe_referentie": null,
  "geplaatst_op": "2026-10-20T08:00:00Z",
  "gewijzigd_op": "2026-11-01T08:00:00Z",
  "passende_kandidaten": 3
}

GET /opdrachten/{opdracht_id}/kandidaten

De kandidaten zoals op de kaart, beste eerst. Recht: kandidaten:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "gegevens": [
    {
      "kandidaat_id": "kand_test0000000000000001",
      "volgorde": 1,
      "naam": "Anna Testpersoon",
      "functie": "Projectmanager",
      "tarief": 95,
      "jaren_ervaring": 12,
      "beschikbaar_vanaf": "2027-01-01",
      "uren_per_week": 32,
      "regio": [
        "Voorbeeldstad"
      ],
      "werkvorm": [
        "hybride"
      ],
      "past_bij_opdracht": {
        "voldoet": 4,
        "voldoet_niet": 0
      },
      "cv_beschikbaar": true,
      "stand": "procedure",
      "profiel_gewijzigd_op": "2026-10-28T09:00:00Z",
      "passend_sinds": "2026-10-30T06:40:00Z",
      "vervallen": false
    }
  ],
  "volgende": null
}

GET /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}

Het profiel (telt als profielbezoek). Recht: kandidaten:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "kandidaat_id": "kand_test0000000000000001",
  "opdracht_id": "opd_test0000000000000001",
  "naam": "Anna Testpersoon",
  "functie": "Projectmanager",
  "tarief": 95,
  "jaren_ervaring": 12,
  "beschikbaar_vanaf": "2027-01-01",
  "uren_per_week": 32,
  "regio": [
    "Voorbeeldstad"
  ],
  "werkvorm": [
    "hybride"
  ],
  "past_bij_opdracht": {
    "voldoet": 4,
    "voldoet_niet": 0,
    "eisen": [
      {
        "eis": "Hbo werk- en denkniveau",
        "voldoet": true
      },
      {
        "eis": "Ervaring bij een overheidsorganisatie",
        "voldoet": true
      }
    ]
  },
  "werkervaring": [
    {
      "functie": "Projectmanager",
      "opdrachtgever": "Voorbeeld Organisatie",
      "van": "2022-01",
      "tot": null,
      "maanden": 46
    }
  ],
  "opleidingen": [
    "Voorbeeldopleiding (hbo)"
  ],
  "certificaten": [
    "Voorbeeldcertificaat"
  ],
  "vaardigheden": [
    "Plannen",
    "Samenwerken"
  ],
  "talen": [
    "Nederlands",
    "Engels"
  ],
  "cv_beschikbaar": true,
  "stand": "procedure",
  "profiel_gewijzigd_op": "2026-10-28T09:00:00Z"
}

POST /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/contact

Mailadres plus telefoon (telt als contactmoment). Recht: contact:lezen.

curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/contact" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "kandidaat_id": "kand_test0000000000000001",
  "naam": "Anna Testpersoon",
  "mailadres": "anna@voorbeeld.nl",
  "telefoon": "+31 6 00000001",
  "eerste_contactmoment_op": "2026-11-02T09:00:00Z"
}

GET /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/cv

Het cv-bestand (telt als contactmoment). Recht: contact:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/cv" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"

GET /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/stand

De laatste stand plus de bevestiging. Recht: kandidaten:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/stand" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "opdracht_id": "opd_test0000000000000001",
  "kandidaat_id": "kand_test0000000000000001",
  "stand": "procedure",
  "startdatum": null,
  "einddatum": null,
  "reden": null,
  "gemeld_op": "2026-11-02T10:00:00Z",
  "bevestiging": "bevestigd",
  "bevestigd_op": "2026-11-02T12:00:00Z"
}

POST /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/stand

Een stand melden. Recht: stand:schrijven.

curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/stand" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stand-001" \
  -d '{"stand":"aangenomen","startdatum":"2027-01-04","einddatum":"2027-07-02"}'
{
  "opdracht_id": "opd_test0000000000000001",
  "kandidaat_id": "kand_test0000000000000001",
  "stand": "aangenomen",
  "startdatum": "2027-01-04",
  "einddatum": "2027-07-02",
  "reden": null,
  "gemeld_op": "2026-11-20T10:02:00Z",
  "bevestiging": "open",
  "bevestigd_op": null
}

POST /kandidaten/{kandidaat_id}/gewist

Melden dat de gegevens gewist zijn. Recht: stand:schrijven.

curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/kandidaten/kand_test0000000000000001/gewist" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "kandidaat_id": "kand_test0000000000000001",
  "gewist_gemeld_op": "2026-11-12T08:00:00Z"
}

GET /gebeurtenissen

Alle berichten van de laatste 30 dagen (ook zonder berichtenadres). Recht: kandidaten:lezen.

curl "https://zzpdock.nl/api/v1/bemiddelaar/gebeurtenissen" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>"
{
  "gegevens": [
    {
      "gebeurtenis_id": "evt_1q2w3e4r5t6y7u8i9o0p",
      "soort": "stand.bevestigd",
      "aangemaakt_op": "2026-11-21T09:00:00Z",
      "api_versie": "v1",
      "test": true,
      "gegevens": {
        "opdracht_id": "opd_4f8k2m9q1w7x3c5v6b0n",
        "kandidaat_id": "kand_9q2w4e6r8t1y3u5i7o0p",
        "stand": "aangenomen"
      }
    }
  ],
  "volgende": null
}

POST /test/gebeurtenis

Laat ZZPdock een voorbeeldbericht sturen (alleen testsleutel). Alleen met een testsleutel.

curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/test/gebeurtenis" \
  -H "Authorization: Bearer zzpd_test_<jouw testsleutel>" \
  -H "Content-Type: application/json" \
  -d '{"soort":"stand.bevestigd"}'
{
  "gebeurtenis_id": "evt_1q2w3e4r5t6y7u8i9o0p",
  "soort": "stand.bevestigd",
  "aangemaakt_op": "2026-11-21T09:00:00Z",
  "api_versie": "v1",
  "test": true,
  "gegevens": {
    "opdracht_id": "opd_4f8k2m9q1w7x3c5v6b0n",
    "kandidaat_id": "kand_9q2w4e6r8t1y3u5i7o0p",
    "stand": "aangenomen"
  }
}

GET /openapi.json

De machineleesbare beschrijving. Zonder sleutel.

curl "https://zzpdock.nl/api/v1/bemiddelaar/openapi.json"

Berichten

ZZPdock stuurt een bericht naar het adres dat je op het scherm Koppelingen neerzet. Een bericht bevat alleen ID's en nooit persoonsgegevens: je haalt de inhoud op met je sleutel. Ontbreekt het adres dan staan dezelfde berichten 30 dagen in GET /gebeurtenissen.

{
  "gebeurtenis_id": "evt_3n5b7v9c1x2z4l6k8j0h",
  "soort": "kandidaat.passend",
  "aangemaakt_op": "2026-11-11T06:40:12Z",
  "api_versie": "v1",
  "test": false,
  "gegevens": {
    "opdracht_id": "opd_4f8k2m9q1w7x3c5v6b0n",
    "kandidaat_id": "kand_9q2w4e6r8t1y3u5i7o0p"
  }
}

Handtekening controleren

Elk bericht draagt ZZPdock-Handtekening: t=<tijd>,v1=<hmac>. De hmac is HMAC-SHA256 over <tijd>.<inhoud> met het geheim van je adres (whsec_ plus 43 tekens). Gebruik de ruwe inhoud zoals die binnenkomt. Weiger een bericht dat ouder is dan 5 minuten. Na het vernieuwen van het geheim staan er 24 uur twee v1-waarden onder het bericht: elk geheim mag kloppen.

Een voorbeeld dat je kunt narekenen met geheim whsec_VoorbeeldGeheimVoorbeeldGeheimVoorbeeld1234 en tijd 1794303612:

ZZPdock-Handtekening: t=1794303612,v1=fd879adc3b8d457f8b4901ba067554511d34c93ec2cb70fcf3f60fb93c194642

{"gebeurtenis_id":"evt_3n5b7v9c1x2z4l6k8j0h","soort":"kandidaat.passend","aangemaakt_op":"2026-11-11T06:40:12Z","api_versie":"v1","test":false,"gegevens":{"opdracht_id":"opd_4f8k2m9q1w7x3c5v6b0n","kandidaat_id":"kand_9q2w4e6r8t1y3u5i7o0p"}}

Node

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

// kop: de waarde van ZZPdock-Handtekening, inhoud: de ruwe body (niet opnieuw geserialiseerd)
export function controleer(kop, inhoud, geheim, nu = Date.now() / 1000) {
  const delen = kop.split(",")
  const tijd = Number(delen.find((d) => d.startsWith("t="))?.slice(2))
  const waarden = delen.filter((d) => d.startsWith("v1=")).map((d) => d.slice(3))
  if (!Number.isFinite(tijd) || Math.abs(nu - tijd) > 300) return false
  const verwacht = createHmac("sha256", geheim).update(`${tijd}.${inhoud}`).digest()
  return waarden.some((w) => {
    const b = Buffer.from(w, "hex")
    return b.length === verwacht.length && timingSafeEqual(b, verwacht)
  })
}

Python

import hashlib, hmac, time

def controleer(kop, inhoud, geheim, nu=None):
    # kop: de waarde van ZZPdock-Handtekening, inhoud: de ruwe body (bytes)
    nu = nu or time.time()
    delen = kop.split(",")
    tijd = next((int(d[2:]) for d in delen if d.startswith("t=")), None)
    waarden = [d[3:] for d in delen if d.startswith("v1=")]
    if tijd is None or abs(nu - tijd) > 300:
        return False
    verwacht = hmac.new(geheim.encode(), f"{tijd}.".encode() + inhoud, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(w, verwacht) for w in waarden)

Testen

Wijzigingen