Controllo accessi

Obiettivo: far registrare in tempo reale le timbrature in Kinmu al tuo sistema di controllo accessi (tornelli, lettori di badge, chioschi).

Scopes necessari: org:fichajes:write (registrare) e org:fichajes:read (consultare).

Registrare una timbratura

POST /v1/check-ins registra un evento per conto di un dipendente. Viene salvato con source=api, resta tracciato e rispetta le validazioni di orario (nessun bypass delle regole).


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

Campi del body:

Campo	Obbligatorio	Note
`employee_id`	Sì	UUID pubblico del dipendente.
`type`	Sì	`in`, `out`, `break_start` o `break_end`.
`timestamp`	Sì	ISO 8601 in UTC. Deve cadere nella finestra [adesso − 24 h, adesso + 5 min]; fuori da lì → `422 validation_failed`.
`location_id`	No	Sede in cui avviene la timbratura.
`note`	No	Testo libero (ad es. identificativo del lettore).

Risposta 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 finestra di timestamp è stretta: 24 h all’indietro e 5 minuti in avanti. Un lettore che accumula eventi senza rete per più di 24 h si vedrà rifiutare l’intero blocco al ritorno della connessione, evento per evento, con 422. Progetta il buffer perché si svuoti appena c’è rete e tratta quel 422 come un caso da sistemare a mano (o dalla dashboard), non come ritentabile: il retry non passerà comunque.

Usa Idempotency-Key per ogni timbratura. I tornelli riprovano in caso di interruzioni di rete; con una chiave idempotente eviti di registrare due volte lo stesso accesso. Reinviare la stessa chiave restituisce la timbratura originale; riusarla con un altro body dà 409.

Mappare i tuoi dipendenti

Il tuo sistema di accessi identifica le persone per badge o PIN; Kinmu per employee_id (UUID). Costruisci la mappatura una volta e aggiornala periodicamente:

Scarica i dipendenti e la loro struttura


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"

Salva la mappatura `tessera → employee_id` e `zona → location_id`

Usa email o un campo della tua anagrafica per abbinare le persone; salva gli UUID di Kinmu. L’email del dipendente è unica per azienda, non a livello globale: la stessa persona può esistere in un’altra azienda Kinmu senza collidere con la tua.

Se la tua integrazione crea dipendenti (POST /v1/employees), tieni conto che la risposta può essere 402 billing_required: l’abbonamento è vivo ma il piano non ha posti liberi. Non è ritentabile: il piano va ampliato dalla dashboard.

Aggiorna con `updated_since`

Rileggi solo ciò che è cambiato: GET /v1/employees?updated_since=<ultima sync>.

Consultare le timbrature

Per la riconciliazione, leggi gli eventi con un intervallo obbligatorio di ≤ 92 giorni:


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

Vuoi reagire in tempo reale a ogni timbratura (per esempio per un pannello presenze)? Sottoscrivi l’evento checkin.created con i webhooks invece di fare polling.

Errori frequenti

Situazione	Risposta
Manca `org:fichajes:write`	`403 invalid_scope`
`timestamp` fuori finestra (> 24 h nel passato o > 5 min nel futuro) o `type` non valido	`422 validation_failed` (con `errors`)
Retry con la stessa `Idempotency-Key` e body diverso	`409 idempotency_conflict`
Dipendente di un’altra azienda	`404 not_found`
Creazione di un dipendente senza posti liberi nel piano	`402 billing_required`