Contrôle d’accès

Objectif : permettre à votre système de contrôle d’accès (tourniquets, lecteurs de badge, bornes) d’enregistrer des pointages dans Kinmu en temps réel.

Scopes requis : org:fichajes:write (enregistrer) et org:fichajes:read (consulter).

Enregistrer un pointage

POST /v1/check-ins enregistre un événement au nom d’un salarié. Il est persisté avec source=api, audité, et respecte les validations de temps de travail (aucun contournement des règles).


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"
  }'

Champs du body :

Champ	Obligatoire	Notes
`employee_id`	Oui	UUID public du salarié.
`type`	Oui	`in`, `out`, `break_start` ou `break_end`.
`timestamp`	Oui	ISO 8601 en UTC.
`location_id`	Non	Site où a lieu le pointage.
`note`	Non	Texte libre (p. ex. identifiant du lecteur).

Réponse 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"
}

Utilisez Idempotency-Key sur chaque pointage. Les tourniquets réessaient en cas de coupure réseau ; avec une clé idempotente, vous évitez d’enregistrer deux fois le même accès. Renvoyer la même clé retourne le pointage d’origine ; la réutiliser avec un autre body renvoie un 409.

Mapper vos salariés

Votre système d’accès identifie les personnes par badge ou PIN ; Kinmu par employee_id (UUID). Construisez le mapping une fois, puis rafraîchissez-le périodiquement :

Téléchargez les salariés et leur structure


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"

Stockez le mapping `carte → employee_id` et `zone → location_id`

Utilisez email ou un champ de votre référentiel pour faire correspondre les personnes ; stockez les UUID de Kinmu.

Rafraîchissez avec `updated_since`

Ne relisez que ce qui a changé : GET /v1/employees?updated_since=<dernière sync>.

Consulter les pointages

Pour la réconciliation, lisez les événements avec une plage obligatoire de ≤ 92 jours :


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

Vous voulez réagir en temps réel à chaque pointage (par exemple pour un tableau de présence) ? Abonnez-vous à l’événement checkin.created avec les webhooks plutôt que de faire du polling.

Erreurs fréquentes

Situation	Réponse
Scope `org:fichajes:write` manquant	`403 invalid_scope`
`timestamp` hors plage ou `type` invalide	`422 validation_failed` (avec `errors`)
Nouvelle tentative avec la même `Idempotency-Key` et un body différent	`409 idempotency_conflict`
Salarié d’une autre entreprise	`404 not_found`