Endpunkt Referenz

Endpunkt-Referenz

Übersicht aller 313 Routen der API (v1.2.0), gruppiert nach Familien. Diese Seite ist eine kompakte Landkarte — Request-/Response-Schemata, Parameter und Beispiele liefert die interaktive Dokumentation einer laufenden Instanz: Swagger UI unter /api/v1/docs (ReDoc: /api/v1/redoc, OpenAPI-Schema: /api/v1/openapi.json; Anmeldung erforderlich).

Präfix: Alle Routen liegen unter /api und identisch unter /api/v1 (empfohlen; unversionierte Aufrufe erhalten Deprecation-Header, siehe Installation-und-Betrieb).

Legende Rollen:

Kürzel	Bedeutung
P	öffentlich (kein Token)
L	Leser — jeder angemeldete Benutzer
PL	Planer oder höher
A	Admin

Schreibrouten erzwingen zusätzlich die granularen Schreibrechte des Benutzerkontos (WDUTIES, WABSENCES, …); WPAST=0 blockiert jede Schreiboperation mit Datum in der Vergangenheit. Details: Authentifizierung-und-Rechte.

---

Health / System / Dashboard

Methode	Pfad	Rolle	Zweck
GET	/api	P	Service-Info
GET	/api/health	P	Aggregierter Health-Check (DB/Disk/Memory/Uptime/Sessions)
GET	/api/metrics	P	In-Process-Metriken (Requests, Fehlerrate, Cache-Hitrate, DB-Latenz)
GET	/api/version	P	API-Version, Python-Version, min_compatible_frontend
GET	/api/dev/mode	P	Ist der Dev-Modus aktiv?
GET	/api/migration/status	L	Schema-Version DBF bzw. Alembic-Revision (PostgreSQL)
GET	/api/stats	L	Datenbank-Statistik
GET	/api/dashboard/summary	L	Dashboard-KPIs (Besetzung, Abwesenheiten, Zeitkonto-Alerts, Geburtstage, Unterbesetzungswarnungen)
GET	/api/dashboard/today	L	Heute im Dienst / abwesend, Wochenpeak
GET	/api/dashboard/upcoming	L	Nächste Feiertage, Geburtstage der Woche
GET	/api/dashboard/stats	L	Monats-KPIs, Coverage pro Tag, Mitarbeiter-Ranking
GET	/ + /{path}	P	SPA-Auslieferung (nur bei vorhandenem Frontend-Build)

Auth, Benutzer & 2FA

Methode	Pfad	Rolle	Zweck
POST	/api/auth/login	P	Login (Rate-Limit, Brute-Force-Lockout); bei aktivierter 2FA zweistufig
POST	/api/auth/logout	P	Session-Invalidierung + Cookie-Löschung
GET	/api/auth/me	L	Aktueller Benutzer inkl. permissions-Objekt
POST	/api/auth/change-password	L	Eigenes Passwort ändern (andere Sessions werden beendet)
GET/POST	/api/users	A	Benutzer auflisten / anlegen
PUT/DELETE	/api/users/{user_id}	A	Benutzer ändern / löschen (Soft-Delete + Session-Revoke)
POST	/api/users/{user_id}/change-password	A	Passwort setzen (Token-Rotation)
POST	/api/users/{user_id}/reset-password	PL	Temporäres Passwort generieren (E-Mail-Versand falls SMTP konfiguriert)
GET	/api/auth/2fa/status	L	TOTP aktiviert?
POST	/api/auth/2fa/setup	L	TOTP-Secret + QR-Code (base64-PNG)
POST	/api/auth/2fa/enable	L	Code verifizieren, 2FA aktivieren, Backup-Codes erhalten
POST	/api/auth/2fa/disable	L	2FA deaktivieren (Passwort-Bestätigung)
POST	/api/auth/2fa/admin-disable/{user_id}	A	2FA fremddeaktivieren (z. B. Geräteverlust)

Firmen / Multi-Tenant

Methode	Pfad	Rolle
GET	/api/companies, /api/companies/{id}	A
POST	/api/companies	A
PUT/DELETE	/api/companies/{id}	A (Löschen = Soft-Delete; 409 bei zugeordneten Mitarbeitern/Gruppen)

Mitarbeiter & Gruppen

Methode	Pfad	Rolle
GET	/api/employees, /api/employees/{id}	L (Filter include_hidden, group_id, Pagination)
POST	/api/employees	A oder explizites ADDEMPL-Recht
PUT/DELETE	/api/employees/{id}	A (Löschen = Soft-Delete/Verstecken)
PUT	/api/employees/{id}/activate	A (Reaktivieren)
GET/POST	/api/employees/{id}/photo	L / A (Foto-Abruf bzw. Upload, Konvertierung nach WebP)
POST	/api/employees/import-csv	A (CSV-Import)
POST	/api/employees/bulk	A (Bulk: verstecken/anzeigen/Gruppe zuweisen)
GET/POST	/api/groups, PUT/DELETE /{id}	L / A
GET	/api/groups/{id}/members	L
POST/DELETE	/api/groups/{id}/members(/{emp_id})	A
GET	/api/group-assignments	L (alle Mitarbeiter↔Gruppe-Zuordnungen)
GET	/api/employees/qualification-matrix	PL (Qualifikations-Matrix)
GET	/api/qualifications/stats	PL
GET/POST/PUT	/api/employees/{id}/availability	PL (Verfügbarkeiten)

Dienstplan

Methode	Pfad	Rolle
GET	/api/schedule	L (Monatsplan, Gruppe optional)
GET	/api/schedule/day · /week · /year	L
GET	/api/schedule/coverage	L (Besetzungsanalyse gegen den Personalbedarf: je Tag Ist/Min/Max und Status under/ok/over/none)
GET	/api/schedule/conflicts	L (Konflikterkennung)
POST	/api/schedule	PL (Eintrag anlegen, mit Konflikt-/Restriktionsprüfung)
DELETE	/api/schedule/{employee_id}/{date}	PL
DELETE	/api/schedule-shift/{employee_id}/{date}	PL (nur Schicht-Override)
POST	/api/schedule/bulk · /bulk-group	PL (Bulk-Operationen, Gruppen-Zuweisung)
POST	/api/schedule/generate	PL (Auto-Generierung aus Schichtzyklen)
POST	/api/schedule/swap	PL (Diensttausch zwischen zwei Mitarbeitern)
POST	/api/schedule/copy-week	PL
GET/POST	/api/schedule/templates, POST /capture, DELETE /{id}, POST /{id}/apply	PL (Wochen-Templates)
GET	/api/cycles	L
GET/POST	/api/shift-cycles, GET/PUT/DELETE /{id}	L / PL (Schichtzyklen)
GET/POST/DELETE	/api/shift-cycles/assign(/{employee_id})	PL (Zyklus-Zuweisungen)
GET/POST/DELETE	/api/cycle-exceptions(/{id})	PL (Zyklus-Ausnahmen)
GET	/api/staffing	L (Soll/Ist pro Monat)
GET/POST/DELETE	/api/restrictions(/{employee_id}/{shift_id})	L / A (Schichtsperren)
POST/GET/PUT/DELETE	/api/einsatzplan(/{id}), POST /deviation	PL (Einsatzplan & Abweichungen)
GET/POST/DELETE	/api/schedule/comments(/{id})	L / PL (Tageskommentare)
GET	/api/schedule/pdf	PL (druckfertige HTML-Ansicht, A4 quer)

Abwesenheiten & Urlaub

Methode	Pfad	Rolle
GET	/api/absences	L (Filter Jahr/Monat/Mitarbeiter/Typ, Pagination)
POST	/api/absences	PL (mit Urlaubssperren- und Saldo-Prüfung; Teiltags-Intervalle möglich)
POST	/api/absences/bulk	PL (mehrere Mitarbeiter)
DELETE	/api/absences/{employee_id}/{date}	PL
GET	/api/absences/status	PL (Genehmigungsstatus)
PATCH	/api/absences/{id}/status	PL (genehmigen/ablehnen + Benachrichtigung)
GET	/api/absences/stats/employee/{id} · /group/{id} · /overview	PL
GET/POST	/api/leave-entitlements	L / PL (Urlaubsansprüche)
POST	/api/leave-entitlements/forfeit	A (Stichtags-Verfall von Resturlaub, mit dry_run-Vorschau)
GET	/api/leave-balance, /api/leave-balance/group	L (Resturlaub)
GET/POST/DELETE	/api/holiday-bans(/{id})	L / A (Urlaubssperren)
GET	/api/annual-close/preview	A (Jahresabschluss-Vorschau)
POST	/api/annual-close	A (Salden-Übertrag ins Folgejahr, optional keep_entitlements)

Stammdaten

Methode	Pfad	Rolle
GET/POST	/api/shifts, PUT/DELETE /{id}	L / A (Schichtarten; Löschen = Soft-Hide bei aktiver Nutzung)
GET/POST	/api/leave-types, PUT/DELETE /{id}	L / A (Abwesenheitsarten)
GET/POST	/api/holidays, PUT/DELETE /{id}	L / A (Feiertage, inkl. halbe und folgejahresbezogene)
GET/POST	/api/workplaces, PUT/DELETE /{id}	L / A (Arbeitsplätze)
GET	/api/workplaces/{id}/employees	L
POST/DELETE	/api/workplaces/{id}/employees/{emp_id}	A
GET/POST	/api/extracharges, PUT/DELETE /{id}, GET /summary	L / A (Zuschläge; /summary für Monat oder freien Zeitraum)
GET/POST	/api/staffing-requirements	L / PL (Personalbedarf je Wochentag, Feiertags-Slot inklusive)
GET/POST	/api/staffing-requirements/special, PUT/DELETE /{id}	L / PL (datumsbezogener Sonderbedarf)
GET/POST	/api/skills, PUT/DELETE /{id}	L / A (Skills)
GET/POST/DELETE	/api/skills/assignments(/{id})	L / A
GET	/api/skills/matrix	L (Mitarbeiter × Skills)

Reports, Statistiken, Export/Import

→ ausführlich beschrieben unter Berichte-und-Exporte

Methode	Pfad	Rolle	Format/Zweck
GET	/api/statistics	L	Soll/Ist/Überstunden je Mitarbeiter, Monat oder freier Zeitraum from/to
GET	/api/personnel-table	L	Personaltabelle über freien Zeitraum (Standard- + dynamische Spalten)
GET	/api/statistics/year-summary · /employee/{id} · /sickness · /shifts	L	Jahresübersicht, Einzelstatistik, Krankenstand, Schicht-Trend
GET	/api/export/schedule · /statistics	L	csv / html / xlsx
GET	/api/export/employees · /absences	L	csv
GET	/api/reports/monthly	L	Monatsabschluss csv / pdf
GET	/api/zeitkonto · /detail · /summary	L	Zeitkonto (Saldo, Verlauf, Teamsummen)
GET/POST/DELETE	/api/bookings(/{id})	L / PL	Manuelle Stundenbuchungen
GET/POST	/api/bookings/carry-forward	L / PL	Übertragssaldo
POST	/api/bookings/annual-statement	PL	Jahresabrechnung
GET	/api/overtime-records	L	Überstunden-Einträge
GET	/api/employees/{id}/overtime	PL	Über-/Unterstunden je Monat
GET	/api/overtime/summary	PL	Team-Überstunden
GET	/api/overtime-summary	L	(ältere Variante)
POST	/api/import/employees · /shifts · /absences · /holidays · /bookings-actual · /bookings-nominal · /entitlements · /absences-csv · /groups	A	CSV-Importe (max. 10 MB)
GET	/api/burnout-radar · /warnings · /fairness · /quality-report · /availability-matrix	L	Analysen
GET	/api/capacity-forecast · /api/capacity-year	L	Kapazitätsprognose
POST	/api/simulation	L	Was-wäre-wenn-Simulation
GET	/api/reports/conflicts(/export)	PL	Konfliktreport (Export: csv / xlsx)

Self-Service, Notizen, Wünsche, Tauschbörse

Methode	Pfad	Rolle
GET/POST	/api/notes, PUT/DELETE /{id}	L / PL (Schichtnotizen)
GET	/api/search	L (Volltextsuche über Mitarbeiter/Schichten/Gruppen/…)
GET/POST/DELETE	/api/employee-access(/{id})	A (Zugriffsrechte je Mitarbeiter)
GET/POST/DELETE	/api/group-access(/{id})	A (Zugriffsrechte je Gruppe)
GET/POST	/api/changelog	L / PL (Aktivitätsprotokoll)
GET/POST	/api/wishes, DELETE /{id}, PATCH /{id}/approve	L / PL (Schichtwünsche/Sperrtage)
GET/POST	/api/handover, PATCH/DELETE /{id}	L / PL (Übergabebuch)
GET/POST	/api/swap-requests, PATCH /{id}/resolve, DELETE /{id}	L / PL (Tauschbörse; bei Annahme echter Plan-Tausch + Benachrichtigung)
GET	/api/shifts/swap/{id}/history	L
POST	/api/shifts/swap/expire	PL (alte Anfragen ablaufen lassen)
POST/PATCH/DELETE	/api/self/swap-requests(/{id}[/respond])	L (eigene Tauschanträge)
GET	/api/me/employee	L (eigener Mitarbeiterdatensatz)
GET/POST/DELETE	/api/self/wishes(/{id})	L
GET	/api/self/schedule	L
POST	/api/self/absences	L (eigener Abwesenheitsantrag → Genehmigungsworkflow)
GET	/api/release-notes	L (liefert das CHANGELOG)

Admin, Backup, Settings

Methode	Pfad	Rolle
GET/POST/DELETE	/api/periods(/{id})	L / A (Abrechnungsperioden)
GET/PUT	/api/settings	L / A (Programmeinstellungen)
GET	/api/admin/backups	A (ZIP-Backups, Rotation auf 7)
GET/DELETE	/api/admin/backups/{filename}(/download)	A
GET	/api/backup/download	A (Live-ZIP der Datenbankdateien)
GET	/api/backup/sqlite	A (Export als SQLite)
POST	/api/backup/restore	A (ZIP-Upload mit Validierung)
POST	/api/admin/compact	A (Datenbank komprimieren/PACK)
POST	/api/errors	P (Frontend-Error-Reports)
GET	/api/admin/frontend-errors	A
GET	/api/admin/rate-limits	A (429-Ereignis-Dashboard)
GET	/api/admin/cache-stats	A (Response-Cache-Statistik)

Events, Notifications, iCal, E-Mail

Methode	Pfad	Rolle
GET	/api/events	L (SSE-Stream; Token auch als ?token=-Query-Parameter; Keepalive alle 25 s)
GET	/api/notifications	L (eigene ungelesene)
GET	/api/notifications/all	A
PATCH	/api/notifications/{id}/read, /api/notifications/read-all	L
DELETE	/api/notifications/{id}	L
GET/PUT	/api/notifications/settings	L (E-Mail-Trigger je Benutzer)
GET	/api/ical/my-schedule.ics	L (Monats-Download)
GET	/api/ical/schedule/{employee_id}.ics	PL
GET	/api/ical/feed/{token}.ics	P (Token-in-URL für Kalender-Abos; rollierendes Fenster −1/+3 Monate)
POST/GET/DELETE	/api/ical/token	L (Feed-Token erzeugen/abfragen/widerrufen; liefert auch webcal://-URL)
GET	/api/email/config	A (SMTP-Status)
POST	/api/email/test	A

Webhooks

Methode	Pfad	Rolle
GET	/api/webhooks, /api/webhooks/{id}	A
POST	/api/webhooks	A (Secret wird generiert)
PUT/DELETE	/api/webhooks/{id}	A
POST	/api/webhooks/{id}/test	A
GET	/api/webhooks/events/list	A

Ereignisse: shift.created/updated/deleted, absence.created/approved. Auslieferung mit HMAC-SHA256-Signatur (X-SP5-Signature) und 3 Retries mit Backoff.

Wiederkehrende Schichten, Scheduler, Arbeitszeitregeln

Methode	Pfad	Rolle
GET/POST	/api/shifts/recurring, DELETE /{id}, POST /{id}/generate	PL (wöchentliche/14-tägige Muster)
GET/POST	/api/export-scheduler/schedules, PUT/DELETE /{id}, POST /{id}/run	PL / A (Excel/CSV-Export per E-Mail)
GET/POST	/api/scheduled-reports, GET/PUT/DELETE /{id}, POST /{id}/run, GET /scheduler/status	PL / A (zeitgesteuerte Berichte, siehe Berichte-und-Exporte)
GET/PUT	/api/work-time-rules	L / A (Arbeitszeitregeln)
POST	/api/work-time-rules/check · /check-all	L (Verstoß-Prüfung: Ruhezeiten, max. Folgetage, …)

ORM-Mirror (/api/admin/orm, nur Admin)

POST /sync materialisiert die DBF-Tabellen über die Bibliothek in eine SQLite-Projektion; GET /status zeigt den Sync-Stand. Dazu Read-only-Listen: /shifts, /leave-types, /workplaces, /shift-assignments, /special-shifts, /absences, /holidays, /periods, /bookings, /overtime, /leave-entitlements, /shift-demands, /special-demands, /cycles, /cycle-assignments, /restrictions — der schrittweise DBF→ORM-Migrationspfad der Bibliothek (siehe Lib-Wiki).

---

Siehe auch

• Authentifizierung-und-Rechte — Rollen und granulare Schreibrechte
• Berichte-und-Exporte — Formate und Scheduler im Detail
• App-Wiki → API-Versionierung