LeaveFlow: REST-API

REST-API von LeaveFlow: Bearer-Token, Mitarbeiter-Endpunkte unter /api/v1/employees, Fehlerformat und Verhalten bei der Anlage.

English Version

Zurück zur Übersicht

LeaveFlow: REST-API

Die REST-API ermöglicht Integrationen wie HR-Systeme: Mitarbeiter lesen, anlegen und ändern. Sie authentifiziert per Bearer-Token und antwortet mit JSON.

Die interaktive Swagger UI deiner Instanz liegt unter /api/doc, die OpenAPI-Beschreibung unter /api/doc.json. Beide sind ohne Anmeldung erreichbar.

Authentifizierung

Jede Anfrage unter /api/ (außer der Dokumentation) braucht einen Token im Header:

Authorization: Bearer DEIN_API_TOKEN

Token erzeugen

Als Admin unter API-Zugriffstoken (/admin/api-tokens) auf Token erstellen klicken.
Einen Namen und optional ein Ablaufdatum in der Zukunft eintragen.
Auf Token generieren klicken und den Token sofort kopieren. Er wird nur einmal angezeigt.

LeaveFlow speichert nur den SHA-256-Hash des Tokens. Ein Token gehört zum Unternehmen und ist nach Widerruf (Widerrufen in der Liste) oder Ablauf sofort ungültig. Eine Detailseite pro Token gibt es nicht.

Basis-URL

https://<deine-domain>/api/v1

Endpunkte

Methode	Pfad	Zweck	Erfolg
`GET`	`/employees`	Alle Mitarbeiter auflisten, auch bereits ausgetretene	`200`
`GET`	`/employees/{id}`	Einen Mitarbeiter lesen	`200`
`POST`	`/employees`	Mitarbeiter mit Benutzerkonto anlegen	`201`
`PATCH`	`/employees/{id}`	Mitarbeiter teilweise ändern	`200`
`DELETE`	`/employees/{id}`	Austritt anstoßen (nicht verlässlich, siehe unten)	`204`

Mitarbeiter-Objekt

Feld	Typ	Beschreibung
`id`	Ganzzahl	Interne ID
`name`	String	Vollständiger Name
`employeeNumber`	String	Personalnummer
`email`	String oder null	E-Mail des verknüpften Benutzerkontos
`locationId`, `locationName`	Ganzzahl, String	Standort
`joinedAt`	String	Eintritt, `JJJJ-MM-TT`
`leftAt`	String oder null	Austritt, `JJJJ-MM-TT`
`weeklyHours`	Zahl	Wochenstunden
`userId`	Ganzzahl oder null	ID des Benutzerkontos

GET /employees liefert alle Mitarbeiter des Unternehmens, ausgetretene eingeschlossen (erkennbar an leftAt).

Mitarbeiter anlegen

Feld	Pflicht	Beschreibung
`name`	ja	Höchstens 150 Zeichen
`email`	ja	Gültige E-Mail-Adresse des Benutzerkontos
`employeeNumber`	ja	Höchstens 50 Zeichen, eindeutig im Unternehmen
`locationId`	ja	ID eines Standorts des Unternehmens
`joinedAt`	ja	Datum `JJJJ-MM-TT`
`weeklyHours`	nein	Größer 0, Standard `40.0`
`role`	nein	`employee` (Standard) oder `manager`

curl -X POST "https://<deine-domain>/api/v1/employees" \
  -H "Authorization: Bearer DEIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Anna Neu","email":"anna.neu@example.com","employeeNumber":"EMP-010","locationId":1,"joinedAt":"2026-07-01","weeklyHours":40.0,"role":"employee"}'

Die Arbeitszeit wird gleichmäßig auf Montag bis Freitag verteilt.
Die Rolle admin lehnt die API mit 422 ab („Role "admin" cannot be assigned via the API.“). Ein anderer unbekannter Wert wird stillschweigend zu employee.
Es wird keine Einladungs-E-Mail verschickt, und das Benutzerkonto hat kein Passwort. Die Person setzt es über „Passwort vergessen?“ oder du löst im Admin unter Benutzer die Aktion Reset senden aus.
Eine vergebene Personalnummer liefert 422 („Employee number already in use.“). Ein unbekannter oder fremder locationId liefert 404 („Location not found.“).
Die E-Mail-Adresse wird nicht auf Duplikate geprüft. Ist sie schon vergeben, scheitert der Aufruf an der Datenbank mit einem Serverfehler.

Mitarbeiter ändern

Alle Felder sind optional, nur gesendete Felder werden geändert.

Feld	Beschreibung
`name`	Höchstens 150 Zeichen
`locationId`	ID eines Standorts des Unternehmens, sonst `404`
`weeklyHours`	Größer 0; die Arbeitszeit wird dabei wieder gleichmäßig auf Montag bis Freitag verteilt

Mitarbeiter deaktivieren

Den Endpunkt DELETE /employees/{id} gibt es, er beantwortet Aufrufe mit 204. Dass das Austrittsdatum und die Deaktivierung des Benutzerkontos dabei dauerhaft gespeichert werden, ist aber nicht verlässlich. Verlasse dich nicht darauf und erfasse Austritte stattdessen in der Mitarbeiterverwaltung des Admin-Bereichs über Austreten....

Statuscodes und Fehlerformat

Code	Bedeutung
`200`, `201`, `204`	Erfolg
`400`	Fehlerhafter Anfrage-Body
`401`	Authorization-Header vorhanden, aber Token ungültig, widerrufen oder abgelaufen
`404`	Mitarbeiter oder Standort nicht gefunden oder gehört zu einem anderen Unternehmen
`422`	Validierung fehlgeschlagen oder Regel verletzt
`500`	Serverfehler

Sende den Authorization-Header immer mit: Für Anfragen ganz ohne diesen Header ist keine 401-Antwort definiert.

Es gibt keinen Antwortcode 403. Fehler außer 401 haben dieses Format; bei Validierungsfehlern enthält message den Fehlertext, eine Liste einzelner Felder (violations) gibt es nicht:

{ "error": true, "message": "Beschreibung des Fehlers" }

Bei 401 lautet die Antwort so und enthält den Header WWW-Authenticate: Bearer realm="LeaveFlow API":

{ "error": "Unauthorized", "message": "Invalid or expired API token." }