Zutrittskontrolle

Ziel: dein Zutrittskontrollsystem (Drehkreuze, Kartenleser, Kioske) erfasst Stempelungen in Kinmu — in Echtzeit.

Benötigte Scopes: org:fichajes:write (erfassen) und org:fichajes:read (abfragen).

Eine Stempelung erfassen

POST /v1/check-ins erfasst ein Ereignis im Namen einer Person. Es wird mit source=api gespeichert, ist auditiert und respektiert die Arbeitszeit-Validierungen (kein Bypass der Regeln).


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

Felder im Body:

Feld	Pflicht	Hinweise
`employee_id`	Ja	Öffentliche UUID der Person.
`type`	Ja	`in`, `out`, `break_start` oder `break_end`.
`timestamp`	Ja	ISO 8601 in UTC.
`location_id`	Nein	Standort, an dem die Stempelung stattfindet.
`note`	Nein	Freitext (z. B. Kennung des Lesegeräts).

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

Verwende bei jeder Stempelung einen Idempotency-Key. Drehkreuze wiederholen Requests bei Netzausfällen; mit einem Idempotenzschlüssel vermeidest du, denselben Zutritt doppelt zu erfassen. Denselben Key erneut zu senden liefert die ursprüngliche Stempelung; ihn mit einem anderen Body wiederzuverwenden ergibt 409.

Deine Mitarbeitenden mappen

Dein Zutrittssystem identifiziert Personen über Karte oder PIN; Kinmu über die employee_id (UUID). Baue das Mapping einmal auf und aktualisiere es regelmäßig:

Lade die Mitarbeitenden und ihre Struktur herunter


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"

Speichere das Mapping `tarjeta → employee_id` und `zona → location_id`

Nutze email oder ein Feld aus deinem Stammdatensystem, um Personen zuzuordnen; speichere die Kinmu-UUIDs.

Aktualisiere mit `updated_since`

Lies nur, was sich geändert hat: GET /v1/employees?updated_since=<última sync>.

Stempelungen abfragen

Zum Abgleich liest du die Ereignisse mit einem Pflichtbereich von ≤ 92 Tagen:


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

Du willst in Echtzeit auf jede Stempelung reagieren (etwa für ein Anwesenheits-Panel)? Abonniere das Event checkin.created per Webhooks, statt zu pollen.

Häufige Fehler

Situation	Antwort
`org:fichajes:write` fehlt	`403 invalid_scope`
`timestamp` außerhalb des Bereichs oder `type` ungültig	`422 validation_failed` (mit `errors`)
Retry mit gleichem `Idempotency-Key` und anderem Body	`409 idempotency_conflict`
Person eines anderen Unternehmens	`404 not_found`