Toegangscontrole

Doel: je toegangscontrolesysteem (poortjes, kaartlezers, kiosken) laat medewerkers realtime in- en uitklokken in Kinmu.

Vereiste scopes: org:fichajes:write (registreren) en org:fichajes:read (opvragen).

Een check-in registreren

POST /v1/check-ins registreert een klok-event namens een medewerker. Het wordt opgeslagen met source=api, geauditeerd en respecteert de werktijdvalidaties (geen bypass van regels).


curl -s -X POST "$KINMU_BASE_URL/check-ins" \
  -H "Authorization: Bearer $KINMU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "employee_id": "a1b2c3d4-…",
    "type": "in",
    "timestamp": "2026-07-08T08:00:00Z",
    "location_id": "loc-uuid",
    "note": "Acceso puerta principal"
  }'

Velden in de body:

Veld	Verplicht	Opmerkingen
`employee_id`	Ja	Publieke UUID van de medewerker.
`type`	Ja	`in`, `out`, `break_start` of `break_end`.
`timestamp`	Ja	ISO 8601 in UTC.
`location_id`	Nee	Locatie waar het klok-event plaatsvindt.
`note`	Nee	Vrije tekst (bijv. identifier van de lezer).

Response 201:


{
  "id": "ci-uuid",
  "employee_id": "a1b2c3d4-…",
  "type": "in",
  "timestamp": "2026-07-08T08:00:00Z",
  "location": { "id": "loc-uuid", "name": "Sede Madrid" },
  "source": "api",
  "validated": true,
  "created_at": "2026-07-08T08:00:01Z",
  "updated_at": "2026-07-08T08:00:01Z"
}

Gebruik bij elke check-in een Idempotency-Key. Poortjes doen retries bij netwerkstoringen; met een idempotency-key voorkom je dat dezelfde toegang twee keer wordt geregistreerd. Dezelfde key opnieuw sturen geeft de oorspronkelijke check-in terug; hergebruik met een andere body geeft 409.

Je medewerkers mappen

Je toegangssysteem identificeert mensen met een pas of pincode; Kinmu met een employee_id (UUID). Bouw de mapping één keer op en ververs die periodiek:

Download de medewerkers en hun structuur


curl -s "$KINMU_BASE_URL/employees?status=active&limit=100" \
  -H "Authorization: Bearer $KINMU_API_KEY"
curl -s "$KINMU_BASE_URL/locations" -H "Authorization: Bearer $KINMU_API_KEY"

Bewaar de mapping `kaart → employee_id` en `zone → location_id`

Gebruik email of een veld uit je stamgegevens om personen te matchen; sla de Kinmu-UUID’s op.

Ververs met `updated_since`

Lees alleen wat er is gewijzigd: GET /v1/employees?updated_since=<laatste sync>.

Check-ins opvragen

Lees voor reconciliatie de events uit met een verplicht bereik van ≤ 92 dagen:


curl -s "$KINMU_BASE_URL/check-ins?employee_id=a1b2…&from=2026-07-01&to=2026-07-08" \
  -H "Authorization: Bearer $KINMU_API_KEY"

Wil je realtime reageren op elk klok-event (bijvoorbeeld voor een aanwezigheidsbord)? Abonneer je op het event checkin.created met webhooks in plaats van te pollen.

Veelvoorkomende fouten

Situatie	Response
`org:fichajes:write` ontbreekt	`403 invalid_scope`
`timestamp` buiten bereik of ongeldig `type`	`422 validation_failed` (met `errors`)
Retry met dezelfde `Idempotency-Key` en andere body	`409 idempotency_conflict`
Medewerker van een ander bedrijf	`404 not_found`