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. Moet binnen het venster [nu − 24 u, nu + 5 min] vallen; daarbuiten → `422 validation_failed`.
`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"
}

Het venster voor timestamp is smal: 24 uur terug en 5 minuten vooruit. Een lezer die langer dan 24 uur zonder netwerk events opspaart, krijgt bij het herstellen van de verbinding de hele batch geweigerd, event voor event, met 422. Ontwerp de buffer zo dat hij leegloopt zodra er netwerk is, en behandel die 422 als iets om handmatig (of via het dashboard) recht te zetten, niet als iets om opnieuw te proberen: de retry komt er evenmin door.

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. Het e-mailadres van een medewerker is uniek per bedrijf, niet wereldwijd: dezelfde persoon kan in een ander Kinmu-bedrijf bestaan zonder met dat van jou te botsen.

Maakt je integratie medewerkers aan (POST /v1/employees), houd dan rekening met 402 billing_required: het abonnement leeft, maar het pakket heeft geen vrije seats. Dat is niet opnieuw te proberen; het pakket moet in het dashboard worden uitgebreid.

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 het venster (> 24 u in het verleden of > 5 min in de toekomst) 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`
Medewerker aanmaken zonder vrije seat in het pakket	`402 billing_required`