Ereignisse des Personalsystems melden: Eintritt, Austritt und Wechsel per Schnittstelle

Ihr Personalsystem kennt Eintritte und Austritte zuerst. Es meldet sie knooing über die Schnittstelle, und knooing löst dasselbe Bündel aus wie die Oberfläche: Software-Anfragen, Zugriffsanträge mit Freigabe und Geräte-Posten. Die Vorlagen entstehen wie unter Vorlagen für Ein- und Austritt pflegen beschrieben, die Grundlagen der Schlüssel unter API-Schlüssel anlegen.

Warum die Schnittstelle? Niemand muss Eintritte ein zweites Mal erfassen, und der Ablauf beginnt am Tag der Entscheidung statt am Tag, an dem jemand daran denkt.

Schritt 1: Schlüssel mit der richtigen Berechtigung

Öffnen Sie Einstellungen, Integrationen, Schnittstellen und klicken Sie auf Schlüssel anlegen. Tragen Sie einen Namen ein und setzen Sie das Häkchen bei Personalsystem-Ereignisse melden. Geben Sie nur, was das Personalsystem braucht. Nötig sind außerdem die Rechte „Bearbeiten“ in Software-Anfragen und im Servicedesk für die Person, die den Schlüssel ausstellt. Die Bündel entstehen im Namen des technischen Kontos hinter dem Schlüssel.

123

1. 1Name des Schlüssels
2. 2Personalsystem-Ereignisse melden
3. 3Anlegen

Schritt 2: Ereignis senden

Das Personalsystem ruft POST /api/v1/hr-events auf, mit dem Schlüssel im Kopf X-API-Key:

{
  "externalKey": "HR-2026-000123",
  "kind": "joiner",
  "effectiveDate": "2026-11-02",
  "employee": { "name": "Paul Beispiel", "email": "paul.beispiel@beispiel-gmbh.test", "department": "Vertrieb" },
  "template": { "key": "buero" }
}

• externalKey: die Kennung des Ereignisses im Personalsystem, je Mandant eindeutig.
• kind: joiner (Eintritt), leaver (Austritt) oder mover (Wechsel).
• effectiveDate: Eintritts- oder Austrittsdatum, bei Wechsel der Wechseltag.
• employee: name ist Pflicht. Bei leaver und mover ist email Pflicht, die Person wird nur darüber bestimmt.
• template: die Vorlage, entweder { "key": "buero" } mit dem Zuordnungsschlüssel oder { "id": "…" }. Bei mover gelten stattdessen from und to.

Ein Wechsel entzieht die Zugriffe der alten Vorlage, außer denen, die dort als Grundzugang markiert sind, und legt den Eintritt in die neue Vorlage an. Geräte der alten Vorlage werden dabei nicht zurückgenommen.

Warum der Zuordnungsschlüssel? Das Personalsystem kennt Ihre Vorlagen-Kennungen nicht, aber seine eigene Stellenart, und die ordnen Sie dem Schlüssel zu.

Schritt 3: Antwort lesen

Bei Erfolg antwortet knooing mit 201 und den angelegten Bündeln:

{ "eventId": "…", "kind": "joiner", "deduplicated": false,
  "bundles": [{ "id": "…", "direction": "onboarding", "status": "open",
    "spawned": { "softwareItems": 1, "accessItems": 1, "deviceItems": 1 } }] }

Dasselbe Ereignis mit derselben externalKey und demselben Inhalt noch einmal zu senden legt nichts doppelt an: Die Antwort ist 200 mit "deduplicated": true. Das schützt vor doppelten Bündeln, wenn das Personalsystem wiederholt.

Das Bündel sehen Sie im Servicedesk unter Ein-/Austritt, siehe Eintritt oder Austritt anstoßen.

Wenn etwas nicht klappt

• 401, „Ungültiger oder fehlender API-Schlüssel.“ Der Schlüssel fehlt, ist widerrufen oder abgelaufen.
• 422, „Zu dieser E-Mail-Adresse gibt es im Mandanten keine Person. Ein Austritt oder Wechsel braucht eine bekannte Person.“ Die E-Mail-Adresse gehört niemandem im Mandanten. Prüfen Sie die Schreibweise.
• 409, „Die Kennung externalKey wurde bereits mit anderem Inhalt gemeldet.“ Dieselbe Kennung darf nicht für ein anderes Ereignis verwendet werden.
• 404, „template: Keine Vorlage mit dem Zuordnungsschlüssel „…“ in dieser Richtung.“ Der Schlüssel stimmt nicht oder die Vorlage ist deaktiviert. Prüfen Sie ihn unter Ein-/Austritt: Vorlagen.
• 403: Dem Schlüssel fehlen die Rechte „Bearbeiten“ in Software-Anfragen und im Servicedesk.