Control de accesos

Objetivo: que tu sistema de control de accesos (tornos, lectores de tarjeta, kioscos) registre fichajes en Kinmu en tiempo real.

Scopes necesarios: org:fichajes:write (registrar) y org:fichajes:read (consultar).

Registrar un fichaje

POST /v1/check-ins registra un evento en nombre de un empleado. Se persiste con source=api, queda auditado y respeta las validaciones de jornada (no hay bypass de reglas).


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

Campos del body:

Campo	Obligatorio	Notas
`employee_id`	Sí	UUID público del empleado.
`type`	Sí	`in`, `out`, `break_start` o `break_end`.
`timestamp`	Sí	ISO 8601 en UTC.
`location_id`	No	Centro donde ocurre el fichaje.
`note`	No	Texto libre (p. ej. identificador del lector).

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

Usa Idempotency-Key en cada fichaje. Los tornos reintentan ante cortes de red; con una key idempotente evitas registrar el mismo acceso dos veces. Reenviar la misma key devuelve el fichaje original; reutilizarla con otro body da 409.

Mapear tus empleados

Tu sistema de accesos identifica personas por tarjeta o PIN; Kinmu por employee_id (UUID). Construye el mapeo una vez y refréscalo periódicamente:

Descarga los empleados y su estructura


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"

Guarda el mapeo `tarjeta → employee_id` y `zona → location_id`

Usa email o un campo de tu maestro para casar personas; guarda los UUID de Kinmu.

Refresca con `updated_since`

Vuelve a leer solo lo que cambió: GET /v1/employees?updated_since=<última sync>.

Consultar fichajes

Para conciliar, lee los eventos con un rango obligatorio de ≤ 92 días:


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

¿Quieres reaccionar en tiempo real a cada fichaje (por ejemplo, para un panel de presencia)? Suscríbete al evento checkin.created con webhooks en lugar de hacer polling.

Errores frecuentes

Situación	Respuesta
Falta `org:fichajes:write`	`403 invalid_scope`
`timestamp` fuera de rango o `type` inválido	`422 validation_failed` (con `errors`)
Reintento con misma `Idempotency-Key` y body distinto	`409 idempotency_conflict`
Empleado de otra empresa	`404 not_found`