Absences API

Die Absences API verwaltet Abwesenheiten (Urlaub, Krank, Schulung …) inklusive Vertreter (Substitute) und Manager-Genehmigung. Abwesenheiten steuern die Verfügbarkeit bei der Zuweisung: abwesende Agents werden ausgefiltert, und Zuweisungen an Abwesende werden zum Zuweisungszeitpunkt auf den Vertreter umgeleitet.

Typen & Status

AbsenceType: VACATION, SICK, TRAINING, BUSINESS_TRIP, PARENTAL, COMPENSATORY, OTHER
AbsenceStatus: PENDING → APPROVED / REJECTED, CANCELLED

Wird eine bereits genehmigte Abwesenheit wesentlich geändert (z.B. Zeitraum), wechselt sie zurück auf PENDING und muss erneut genehmigt werden.

Endpoints /api/absences

Manager-Logik: Entscheiden darf, wer das passende Recht trägt (approve für Genehmigen, reject für Ablehnen) UND entweder DIREKTER Manager des Antragstellers ist oder absences.editAll besitzt. Die Manager-Beziehung ist bewusst direkt und NICHT transitiv: der Manager des Managers entscheidet nicht mit, solange er nicht selbst eingetragen ist. Die eigene Abwesenheit kann niemand entscheiden (403), auch nicht mit editAll. Dieselben Regeln gelten für den Weg über die Genehmigungs-Inbox — beide laufen durch dieselbe Prüfung. Grundlage ist die Manager-Hierarchie aus Users & Roles.

Art und Grund: eingeschränkte Sichtbarkeit

Die ART einer Abwesenheit ist ein Gesundheitsdatum, sobald sie SICK lauten kann (Art. 9 DSGVO), der GRUND ein Freitext daneben. Beide sind deshalb enger gestellt als die Abwesenheit selbst, die Kalender und Team-Tab jedem Berechtigten zeigen. Art und Grund sieht nur, wer mindestens eine dieser drei Bedingungen erfüllt:

• absences.viewDetails — organisationsweit (Administration/Personal)
• DIREKTER Manager der Zeile — nur für die eigenen Mitarbeiter
• der Inhaber selbst

Allen anderen liefert JEDER Leseweg — Kalender, Team-Tab und Status-Route — type: OTHER und reason: null. Die Felder sind damit kein Beleg dafür, was in der Datenbank steht. Der TeamLead zählt bewusst NICHT dazu: das ist eine Queue-Rolle für Zuweisung und Skills, keine Personalrolle; er sieht den Team-Tab weiterhin, aber ohne Art und Grund.

Der Typ-Filter ist gesperrt, nicht stillgelegt: GET /api/absences?type=SICK verlangt absences.viewDetails und antwortet ohne dieses Recht 403 ABSENCE_VIEW_FORBIDDEN. Würde der Filter stattdessen ignoriert, ließe sich die maskierte Art durch Vergleich der Trefferzahlen zurückrechnen.

Aus demselben Grund verlassen Art und Grund das Produkt auch nicht über Benachrichtigungen: weder E-Mail-Betreff noch Body, Webex-, Teams- oder In-App-Nachricht tragen sie. Die Ablehnungs-Begründung bleibt enthalten — sie ist die Nachricht der Führungskraft an den Betroffenen.

Abwesenheit anlegen

POST /api/absences
{
  "userId": "clx-user",
  "type": "VACATION",
  "startDate": "2026-02-10",
  "endDate": "2026-02-21",
  "allDay": true,
  "reason": "Annual vacation",
  "substituteId": "clx-substitute"
}

Halbtags/zeitgenau: allDay=false → startTime und endTime (HH:MM) sind dann Pflicht. Regeln: endDate ≥ startDate; substituteId ≠ userId; Overlap mit bestehenden Abwesenheiten desselben Users wird abgelehnt. createForTeam/createForAll erlauben das Anlegen für andere.

// allDay=false (partial day)
{ "userId": "clx-user", "type": "OTHER", "startDate": "2026-01-30", "endDate": "2026-01-30",
  "allDay": false, "startTime": "08:00", "endTime": "12:00", "reason": "Doctor appointment" }

Eingabe-Regeln

• Unbekannte Felder werden abgelehnt: ein unbekanntes Feld im Body oder ein Fremd-Parameter an der Kalender-Abfrage ist 400 VALIDATION_ERROR mit Feld-Pfad. Das gilt auch für userId im PATCH: der Inhaber einer Abwesenheit ist nicht änderbar.
• Leeren geht mit null: im PATCH leeren reason und substituteId das Feld, wenn sie als null kommen; ein fehlender Schlüssel lässt es unverändert. Beim Anlegen lässt man ein leeres Feld einfach weg.
• Datumsangaben sind ISO-Strings — ein unlesbares Datum meldet den Feld-Pfad, nicht einen Datenbank-Fehler.
• Parallele Aufrufe: Anlage, Änderung, Stornierung und Entscheidung sind gegen Wettläufe abgesichert. Von zwei gleichzeitigen Anlagen im selben Zeitraum gewinnt eine (die andere bekommt 409), von zwei gleichzeitigen Stornierungen oder Entscheidungen ebenfalls (400) — es gibt kein zweites „Erfolgreich".

Fehlercodes

Verfügbarkeit & Vertretung

Abwesenheiten wirken an zwei Stellen, jeweils im Moment der Zuweisung:

• Filterung: /api/users/assignable und die Assignment-Engine schließen aktuell abwesende Agents aus.
• Substitute-Redirect: Wird einem abwesenden Agent dennoch zugewiesen (z.B. direkt), leitet das System auf dessen Vertreter um. Ist auch dieser abwesend, folgt es der Vertretungskette weiter — über höchstens drei Stationen und ohne Kreise. Bewusstes Zuweisen an einen Abwesenden ist mit ignoreSubstitution=true möglich (siehe assign-Endpoints in Tickets/Incidents/Problems/Changes). Wer den Vorgang am Ende bekommt, ist geprüft verfügbar: die Vertretung muss dieselben Hürden nehmen wie ein direkt gewählter Agent (Postfach, Agent-Gruppe, Zuweisbarkeit), und die Kette muss auf jemandem enden, der selbst nicht abwesend ist. Sonst bleibt der Vorgang beim abwesenden Original — sichtbar dort liegend statt scheinbar in Arbeit. Bei Tickets hält der Verlauf die Tatsache fest, dass die Vertretung nicht übernehmen konnte. Den GRUND nennt nur das Audit-Log (SUBSTITUTE_BLOCKED, wenn der Vertretung eine Berechtigung fehlt; SUBSTITUTE_UNAVAILABLE, wenn die Kette auf einer abwesenden Person endet): dass einer dritten Person ein Recht fehlt, gehört nicht in einen Vorgang, den jeder Beteiligte liest. Beide Einträge hängen an der betroffenen Person, nicht am Vorgang — im Audit-Log sucht man sie also über die Vertretung.

GET /api/absences/user/:userId/status liefert kompakt { isAbsent, absenceType, absenceEndDate, substituteId, substituteName } — z.B. für UI-Hinweise. Die Felder sind gestaffelt: isAbsent bekommt jeder angemeldete Aufrufer, Vertretung und Enddatum (ISO-8601) verlangen absences.viewStatus, und absenceType zusätzlich die Berechtigung für Art und Grund (siehe oben) — sonst steht dort OTHER.