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. Muss im Fenster [jetzt − 24 h, jetzt + 5 Min.] liegen; außerhalb → `422 validation_failed`.
`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"
}

Das Fenster für timestamp ist eng: 24 Stunden zurück und 5 Minuten nach vorn. Ein Leser, der ohne Netz länger als 24 Stunden Ereignisse puffert, bekommt beim Wiederverbinden den ganzen Stapel abgelehnt — Ereignis für Ereignis mit 422. Lege den Puffer so aus, dass er sofort bei Netz leert, und behandle dieses 422 als Fall für die manuelle Nachpflege (oder über das Dashboard), nicht als wiederholbar: Der Retry kommt ebenso wenig durch.

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. Die E-Mail-Adresse einer Person ist pro Unternehmen eindeutig, nicht global: Dieselbe Person kann in einem anderen Kinmu-Unternehmen existieren, ohne mit deinem zu kollidieren.

Legt deine Integration Mitarbeitende an (POST /v1/employees), rechne mit 402 billing_required: Das Abonnement lebt, aber der Tarif hat keinen freien Platz mehr. Das ist nicht wiederholbar — der Tarif muss im Dashboard erweitert werden.

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 Fensters (> 24 h in der Vergangenheit oder > 5 Min. in der Zukunft) 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`
Person anlegen, ohne freien Platz im Tarif	`402 billing_required`