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. Doit tomber dans la fenêtre [maintenant − 24 h, maintenant + 5 min] ; en dehors → `422 validation_failed`.
`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"
}

La fenêtre de timestamp est étroite : 24 h en arrière et 5 minutes en avant. Un lecteur qui accumule des événements hors réseau pendant plus de 24 h verra tout le lot refusé au retour de la connexion, événement par événement, en 422. Prévoyez que le buffer se vide dès que le réseau revient, et traitez ce 422 comme un cas à régulariser à la main (ou depuis le dashboard), pas comme réessayable : la nouvelle tentative ne passera pas davantage.

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. L’e-mail d’un salarié est unique par entreprise, pas globalement : la même personne peut exister dans une autre entreprise Kinmu sans entrer en collision avec la vôtre.

Si votre intégration crée des salariés (POST /v1/employees), attendez-vous à un 402 billing_required : l’abonnement est actif mais le plan n’a plus de siège libre. Ce n’est pas réessayable ; il faut faire évoluer le plan depuis le dashboard.

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 fenêtre (> 24 h dans le passé ou > 5 min dans le futur) 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`
Création d’un salarié sans siège libre dans le plan	`402 billing_required`