Passerkontroll

Mål: att ditt passersystem (spärrar, kortläsare, kiosker) registrerar stämplingar i Kinmu i realtid.

Scopes som krävs: org:fichajes:write (registrera) och org:fichajes:read (läsa).

Registrera en stämpling

POST /v1/check-ins registrerar en händelse för en medarbetares räkning. Den sparas med source=api, granskningsloggas och respekterar arbetstidsvalideringarna (ingen bypass av regler).


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

Fält i bodyn:

Fält	Obligatoriskt	Noteringar
`employee_id`	Ja	Medarbetarens publika UUID.
`type`	Ja	`in`, `out`, `break_start` eller `break_end`.
`timestamp`	Ja	ISO 8601 i UTC.
`location_id`	Nej	Platsen där stämplingen sker.
`note`	Nej	Fritext (t.ex. läsarens identifierare).

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

Använd Idempotency-Key vid varje stämpling. Spärrar gör omförsök vid nätverksavbrott; med en idempotent key undviker du att registrera samma passage två gånger. Skickas samma key igen returneras den ursprungliga stämplingen; återanvänds den med en annan body får du 409.

Mappa dina medarbetare

Ditt passersystem identifierar personer via kort eller PIN; Kinmu via employee_id (UUID). Bygg mappningen en gång och uppdatera den regelbundet:

Hämta medarbetarna och deras struktur


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"

Spara mappningen `kort → employee_id` och `zon → location_id`

Använd email eller ett fält i din masterdata för att matcha personer; spara Kinmus UUID:er.

Uppdatera med `updated_since`

Läs bara om det som ändrats: GET /v1/employees?updated_since=<senaste sync>.

Hämta stämplingar

För avstämning, läs händelserna med ett obligatoriskt intervall på ≤ 92 dagar:


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

Vill du reagera i realtid på varje stämpling (till exempel för en närvaropanel)? Prenumerera på eventet checkin.created med webhooks i stället för att polla.

Vanliga fel

Situation	Svar
`org:fichajes:write` saknas	`403 invalid_scope`
`timestamp` utanför intervallet eller ogiltig `type`	`422 validation_failed` (med `errors`)
Omförsök med samma `Idempotency-Key` och annan body	`409 idempotency_conflict`
Medarbetare i ett annat företag	`404 not_found`