Controle de acesso

Objetivo: fazer com que seu sistema de controle de acesso (catracas, leitores de cartão, quiosques) registre pontos no Kinmu em tempo real.

Scopes necessários: org:fichajes:write (registrar) e org:fichajes:read (consultar).

Registrar um ponto

POST /v1/check-ins registra um evento em nome de um funcionário. Ele é persistido com source=api, fica auditado e respeita as validações de jornada (não há bypass de regras).


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 do body:

Campo	Obrigatório	Notas
`employee_id`	Sim	UUID público do funcionário.
`type`	Sim	`in`, `out`, `break_start` ou `break_end`.
`timestamp`	Sim	ISO 8601 em UTC.
`location_id`	Não	Local onde o ponto acontece.
`note`	Não	Texto livre (por exemplo, identificador do leitor).

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

Use Idempotency-Key em cada ponto. Catracas repetem o envio quando a rede cai; com uma chave idempotente você evita registrar o mesmo acesso duas vezes. Reenviar a mesma chave retorna o ponto original; reutilizá-la com outro body dá 409.

Mapear seus funcionários

Seu sistema de acesso identifica pessoas por cartão ou PIN; o Kinmu, por employee_id (UUID). Construa o mapeamento uma vez e atualize-o periodicamente:

Baixe os funcionários e a estrutura


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"

Guarde o mapeamento `cartão → employee_id` e `zona → location_id`

Use email ou um campo do seu cadastro mestre para relacionar as pessoas; guarde os UUIDs do Kinmu.

Atualize com `updated_since`

Releia apenas o que mudou: GET /v1/employees?updated_since=<última sync>.

Consultar pontos

Para conciliar, leia os eventos com um intervalo obrigatório de ≤ 92 dias:


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

Quer reagir em tempo real a cada ponto (por exemplo, para um painel de presença)? Inscreva-se no evento checkin.created com webhooks em vez de fazer polling.

Erros frequentes

Situação	Resposta
Falta `org:fichajes:write`	`403 invalid_scope`
`timestamp` fora do intervalo ou `type` inválido	`422 validation_failed` (com `errors`)
Nova tentativa com a mesma `Idempotency-Key` e body diferente	`409 idempotency_conflict`
Funcionário de outra empresa	`404 not_found`