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. Måste ligga i fönstret [nu − 24 h, nu + 5 min]; utanför det → `422 validation_failed`.
`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"
}

Fönstret för timestamp är smalt: 24 timmar bakåt och 5 minuter framåt. En läsare som samlar händelser utan nät i mer än 24 timmar får hela satsen avvisad när uppkopplingen kommer tillbaka, händelse för händelse, med 422. Bygg bufferten så att den töms så snart nätet är uppe, och hantera det 422:et som något att stämma av för hand (eller i dashboarden) — inte som något att göra om: omförsöket kommer inte in det heller.

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. Medarbetarens e-postadress är unik per företag, inte globalt: samma person kan finnas i ett annat Kinmu-företag utan att krocka med ert.

Skapar din integration medarbetare (POST /v1/employees) kan svaret bli 402 billing_required: prenumerationen lever, men planen har inga lediga platser. Det går inte att försöka igen — planen måste utökas i dashboarden.

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 fönstret (> 24 h bakåt eller > 5 min framåt) 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`
Skapa medarbetare utan ledig plats i planen	`402 billing_required`