🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowTime API - für präzise Zeiterfassung

Eine vollständige REST API für Zeiterfassung mit Timer-Steuerung, Projektmanagement und detaillierten Statistiken. Perfekt für Time-Tracking-Apps, Abrechnungssysteme und Produktivitätsanalysen.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowtime/timer https://creativeskyline.de/api/flowtime/entries https://creativeskyline.de/api/flowtime/projects https://creativeskyline.de/api/flowtime/stats https://creativeskyline.de/api/flowtime/working-hours https://creativeskyline.de/api/flowtime/shifts
FlowTime-Berechtigung erforderlich
Der Benutzer benötigt eine aktive FlowTime-Berechtigung (tt), um die API nutzen zu können.

1. API-Zugangsdaten abrufen

Bevor Sie die FlowTime API nutzen können, benötigen Sie Ihre persönlichen Zugangsdaten: Melden Sie sich an, navigieren Sie zu Profil → API-Zugang und kopieren Sie Ihren persönlichen API-Key (pk_...).

2. Authentifizierung

Alle API-Anfragen benötigen diesen HTTP-Header:

Authorization: Bearer pk_dein_api_key
Accept: application/json

⏱️ Timer-Steuerung

Timer-Status abrufen

GET /api/flowtime/timer/status

Ruft den aktuellen Timer-Status ab. Zeigt an, ob ein Timer läuft und wie lange. Läuft kein Timer, ist "is_tracking" false und "timer" null. Das Feld "timer.entry_type" (work|break) und "timer.state" (working|on_break) zeigen im Modus "Einfache Zeiterfassung" an, ob gerade gearbeitet oder pausiert wird.

Timer starten

POST /api/flowtime/timer/start

Startet einen neuen Timer. Läuft bereits ein Timer, wird dieser NICHT ersetzt: Die API antwortet mit HTTP 409 und liefert im Feld "data.active_timer_uuid" die UUID des bereits laufenden Timers zurück. Stoppen oder Abbrechen Sie den aktiven Timer zuerst, bevor Sie einen neuen starten. Breaking Change: Das frühere numerische Feld "project_id" wird nicht mehr akzeptiert (Validierungsfehler); das Projekt wird ausschließlich über "project_uuid" angegeben. Im Modus "Einfache Zeiterfassung" sind "description" und "project_uuid" nicht erlaubt (HTTP 422) — der Start entspricht dem Einstempeln.

Request Body:

description string Beschreibung der Tätigkeit (max. 500 Zeichen). Im Modus "Einfache Zeiterfassung" nicht erlaubt.
project_uuid string UUID des zugehörigen Projekts (teamgebunden). Im Modus "Einfache Zeiterfassung" nicht erlaubt.

Timer stoppen

POST /api/flowtime/timer/stop

Stoppt den aktuell laufenden Timer und speichert den Zeiteintrag. Im Projekt-Modus müssen Projekt und Beschreibung gesetzt sein (HTTP 400). Im Modus "Einfache Zeiterfassung" (Ausstempeln) entfallen beide Anforderungen; das gilt auch für eine laufende Pause, die dadurch beendet wird (Gehen aus der Pause). Wie bei Start und Update sind "description"/"project_uuid" dort nicht erlaubt (HTTP 422). HTTP 409, wenn sich der Status zwischenzeitlich geändert hat (z. B. parallel gestartete Pause).

Laufenden Timer aktualisieren

PUT /api/flowtime/timer

Aktualisiert den aktuell laufenden Timer (Beschreibung oder Projekt ändern). Breaking Change: Das frühere numerische Feld "project_id" wird nicht mehr akzeptiert; das Projekt wird ausschließlich über "project_uuid" angegeben. Im Modus "Einfache Zeiterfassung" (und bei laufender Pause) sind "description"/"project_uuid" nicht erlaubt (HTTP 422) — nur "starts_at" bleibt änderbar.

Request Body:

description string Neue Beschreibung
project_uuid string UUID des neuen Projekts (teamgebunden)

Timer abbrechen

DELETE /api/flowtime/timer

Bricht den aktuell laufenden Timer ab, ohne die Zeit zu speichern. Eine laufende Pause kann nicht abgebrochen werden (HTTP 409) — sie muss beendet werden ("Pause beenden") oder es wird ausgestempelt.

Pause starten

POST /api/flowtime/timer/break/start

Nur im Modus "Einfache Zeiterfassung" (sonst HTTP 409). Schließt den laufenden Arbeits-Eintrag und öffnet atomar einen Pausen-Eintrag (entry_type=break). Pausen zählen nie als Arbeitszeit. HTTP 404 ohne laufenden Timer, HTTP 409 wenn bereits pausiert.

Pause beenden

POST /api/flowtime/timer/break/stop

Nur im Modus "Einfache Zeiterfassung" (sonst HTTP 409). Schließt den laufenden Pausen-Eintrag und öffnet atomar einen neuen Arbeits-Eintrag. HTTP 404 ohne laufenden Timer, HTTP 409 wenn nicht pausiert.

📝 Zeiteinträge

Zeiteinträge auflisten

GET /api/flowtime/entries

Ruft alle Zeiteinträge mit optionalen Filtern ab.

Query-Parameter:

start_date string Startdatum (YYYY-MM-DD)
end_date string Enddatum (YYYY-MM-DD)
project_uuid string Filter nach Projekt-UUID
user_uuid string Nur für Teaminhaber (oder Mitglieder mit FlowTime-Vollzugriff): Einträge eines bestimmten Nutzers (UUID) filtern. Mitglieder mit dem Sub-Recht "berichte" sehen team-weite Einträge, ohne dieses Recht nur die eigenen.
entry_type string Filter nach Eintragstyp: "work" oder "break" (Modus "Einfache Zeiterfassung")
limit integer Maximale Anzahl der Einträge (1-500, Standard: 50)
offset integer Offset für Pagination

Zeiteintrag abrufen

GET /api/flowtime/entries/{uuid}

Ruft einen einzelnen Zeiteintrag mit allen Details ab.

Zeiteintrag erstellen

POST /api/flowtime/entries

Erstellt einen manuellen Zeiteintrag (ohne Timer). Start- und Endzeitpunkt sind Pflicht; die Dauer wird serverseitig aus der Differenz berechnet. Breaking Change: Das frühere numerische Feld "project_id" wird nicht mehr akzeptiert; das Projekt wird ausschließlich über "project_uuid" angegeben. Im Modus "Einfache Zeiterfassung" gilt ein anderer Vertrag: "description" und "project_uuid" sind dort NICHT erlaubt, stattdessen kann optional "entry_type" (work|break, Standard: work) gesetzt werden. Validierungsfehler dieses Endpunkts (auch die Modus-Verbote) antworten mit HTTP 400 und {"success": false, "errors": {...}}.

Request Body:

description string Bedingt: Pflicht im Projekt-Modus (max. 500 Zeichen); im Modus "Einfache Zeiterfassung" nicht erlaubt (HTTP 400).
project_uuid string Bedingt: Pflicht im Projekt-Modus (Projekt-UUID, muss zum Team gehören); im Modus "Einfache Zeiterfassung" nicht erlaubt (HTTP 400).
starts_at string * Startzeitpunkt (ISO 8601)
ends_at string * Endzeitpunkt (ISO 8601), muss nach starts_at liegen
entry_type string Nur im Modus "Einfache Zeiterfassung": "work" oder "break" (Standard: work). Im Projekt-Modus nicht erlaubt (HTTP 400).

Zeiteintrag aktualisieren

PUT /api/flowtime/entries/{uuid}

Aktualisiert einen bestehenden Zeiteintrag. Breaking Change: Das frühere numerische Feld "project_id" wird nicht mehr akzeptiert; das Projekt wird ausschließlich über "project_uuid" angegeben. Feldvalidierung antwortet mit HTTP 400. Stempeluhr-Einträge (Pausen, Einträge im Modus "Einfache Zeiterfassung" sowie abgeschlossene Anwesenheitseinträge ohne Projekt und Beschreibung) akzeptieren weder "description" noch "project_uuid" (HTTP 422) — nur Start- und Endzeit sind änderbar; "entry_type" ist unveränderlich. Ein laufender Eintrag (Timer oder Pause) kann hier nicht bearbeitet werden (HTTP 409) — dafür PUT /api/flowtime/timer verwenden.

Request Body:

description string Beschreibung
project_uuid string Projekt-UUID (teamgebunden)
starts_at string Startzeitpunkt (ISO 8601)
ends_at string Endzeitpunkt (ISO 8601)

Zeiteintrag löschen

DELETE /api/flowtime/entries/{uuid}

Löscht einen Zeiteintrag unwiderruflich. Ein laufender Eintrag (Timer oder Pause) kann hier nicht gelöscht werden (HTTP 409) — dafür die Timer-Endpunkte (Stoppen/Abbrechen) verwenden.

📁 Projekte

Projekt-Berechtigungen
Private Projekte können bestimmten Teammitgliedern zugewiesen werden. Anlegen und Bearbeiten von Projekten ist dem Teaminhaber (oder Mitgliedern mit FlowTime-Vollzugriff) vorbehalten.

Projekte auflisten

GET /api/flowtime/projects

Listet alle Projekte auf, zu denen der Benutzer Zugriff hat (inklusive Zeitstatistiken).

Projekt-Details abrufen

GET /api/flowtime/projects/{uuid}

Ruft Details eines einzelnen Projekts ab, inklusive Zeitstatistiken. Das Projekt wird über seine UUID adressiert; numerische IDs werden nicht mehr akzeptiert (HTTP 404).

Projekt anlegen

POST /api/flowtime/projects

Erstellt ein neues Projekt (nur Teaminhaber oder Mitglieder mit FlowTime-Vollzugriff). Breaking Change: Der Kunde wird über client_uuid übergeben; das frühere numerische Feld client_id wird nicht mehr akzeptiert (Validierungsfehler).

Request Body:

name string * Projektname (max. 255 Zeichen)
client_uuid string * UUID des CRM-Kunden, der zum Team gehören muss
description string Projektbeschreibung
color_code string Hex-Farbe (z.B. #10B981, Standard: #3B82F6)
is_public boolean Für alle Teammitglieder sichtbar (Standard: true)
is_billable boolean Projekt ist abrechenbar (Standard: false)
billable_rate number Stundensatz für die Abrechnung
currency string Währungscode nach ISO 4217 (3 Zeichen, Standard: Team-Währung)

Projekt aktualisieren

PUT /api/flowtime/projects/{uuid}

Aktualisiert ein bestehendes Projekt (nur Teaminhaber oder Mitglieder mit FlowTime-Vollzugriff). Das Projekt wird über seine UUID adressiert; numerische IDs werden nicht mehr akzeptiert (HTTP 404).

Request Body:

name string Projektname (max. 255 Zeichen)
description string Projektbeschreibung
status string Projektstatus: active oder archived
color_code string Hex-Farbe (z.B. #10B981)
is_public boolean Für alle Teammitglieder sichtbar
is_hidden boolean Projekt in Listen ausblenden
is_billable boolean Projekt ist abrechenbar
billable_rate number Stundensatz für die Abrechnung
currency string Währungscode nach ISO 4217 (3 Zeichen)

Projekt-Berechtigungen setzen

PUT /api/flowtime/projects/{uuid}/permissions

Legt fest, welche Teammitglieder Zugriff auf ein privates Projekt haben (nur Teaminhaber oder Mitglieder mit FlowTime-Vollzugriff). Die übergebene Liste ersetzt die bestehenden Berechtigungen vollständig. Nur Nutzer, die zum Team gehören, werden übernommen.

Request Body:

user_uuids array * Liste der Nutzer-UUIDs, die Zugriff erhalten sollen
user_uuids.* string * Einzelne Nutzer-UUID (gültiges UUID-Format)

Projekt löschen

DELETE /api/flowtime/projects/{uuid}

Entfernt ein Projekt aus FlowTime (nur Teaminhaber oder Mitglieder mit FlowTime-Vollzugriff). Wie in der Weboberfläche muss das Projekt zuvor archiviert sein, sonst antwortet die Schnittstelle mit HTTP 409 und dem Fehler project_not_archived. Ein Projekt, auf das noch Zeiteinträge gebucht sind, bleibt erhalten und antwortet mit HTTP 409 und dem Fehler project_has_entries, damit gebuchte Stunden ihr Projekt nie verlieren. Gelöscht wird nur die FlowTime-Seite des Projekts; der Kundenprojekt-Datensatz in FlowCRM bleibt unberührt.

📑 Kontext, Berichte und Suche

Sub-Rechte entscheiden über die Berichte
Der Detailbericht setzt das Sub-Recht berichte voraus, der Teambericht teamberichte, das Protokoll protokolle. Der Teaminhaber und Konten mit FlowTime-Vollzugriff haben alle drei. Fehlt das Recht, antwortet die Schnittstelle mit HTTP 403 und dem Fehler report_not_available.
Fremde Personen sind schlicht abwesend
Wer die Zahlen einer anderen Person nicht sehen darf, bekommt auf deren user_uuid HTTP 404 und nicht HTTP 403. So verrät die Schnittstelle nicht, ob es das Konto gibt.

Modul-Kontext abrufen

GET /api/flowtime/context

Liefert das Arbeitszeitmodell des Teams, die eigenen Sub-Rechte, die Arbeitszeitvorgaben und den Zustand der Stempeluhr. Ein Client braucht das vor dem ersten Schreibzugriff: im Modus "Einfache Zeiterfassung" trägt ein Eintrag weder Projekt noch Beschreibung, und die Schicht-Endpunkte stehen nur bereit, wenn das Team die Schichtplanung eingeschaltet hat. Der Zustand der Stempeluhr ist einer von clocked_out, clocked_in, on_break oder inactive.

GET /api/flowtime/search

Durchsucht die FlowTime-Datensätze einer Art. Die Sichtbarkeit folgt den Rechten des Schlüssels: ohne Berichtsrechte erscheinen nur die eigenen Zeiteinträge, Projekte nur mit dem Sub-Recht projekte, Kunden nur für den Teaminhaber. Eine Art, die der Schlüssel nicht erreicht, antwortet mit HTTP 403 und dem Fehler record_type_not_available.

Query-Parameter:

type string * Art des Datensatzes: entry, project, client, member, shift_plan, shift_type oder shift_template
q string Suchbegriff; trifft den Namen des Datensatzes, bei Mitgliedern zusätzlich die Mailadresse
from string Nur für type=entry: frühestes Startdatum (YYYY-MM-DD)
to string Nur für type=entry: spätestes Startdatum (YYYY-MM-DD)
user_uuid string Nur für type=entry: grenzt auf die Einträge einer Person ein; fremde Personen erfordern das Sub-Recht teamberichte
page integer Seitenzahl, ab 1
per_page integer Einträge pro Seite, 1-200 (Standard 50)

Detailbericht abrufen

GET /api/flowtime/reports/{report}

Liefert einen der vier Berichte. Der Pfadabschnitt report ist detailed, team, overtime oder logs. detailed gibt die abgeschlossenen Arbeitseinträge eines Zeitraums seitenweise zurück (Standard ist der laufende Monat) und akzeptiert from, to und user_uuid. team liefert je Teammitglied die Monatsauswertung und akzeptiert year und month. overtime gibt den Überstundensaldo der laufenden Woche zurück, standardmäßig den eigenen; eine fremde user_uuid ist dem Teaminhaber vorbehalten. logs gibt die Protokollzeilen des Moduls seitenweise zurück.

Query-Parameter:

from string Nur detailed: Beginn des Zeitraums (YYYY-MM-DD), Standard Monatsbeginn
to string Nur detailed: Ende des Zeitraums (YYYY-MM-DD), Standard heute
year integer Nur team: Jahr der Auswertung, Standard laufendes Jahr
month integer Nur team: Monat der Auswertung (1-12), Standard laufender Monat
user_uuid string Für detailed und overtime: die Person, deren Zahlen gemeint sind
page integer Für detailed und logs: Seitenzahl, ab 1
per_page integer Für detailed und logs: Einträge pro Seite, 1-200 (Standard 50)

📊 Statistiken

Statistik-Endpoints liefern aggregierte Auswertungen der erfassten Zeiten. GET /api/flowtime/stats/today gibt die Tagesauswertung zurück, GET /api/flowtime/stats/week die Wochenauswertung mit täglicher Aufschlüsselung und Projekt-Anteilen.

Breaking Change: Die Projekt-Aufschlüsselung unter data.by_project weist das Projekt über project_uuid aus. Das frühere numerische project_id entfällt ersatzlos.

Pausen (Modus "Einfache Zeiterfassung"): break_seconds enthält die abgeschlossenen Pausen des Tages und den bereits verstrichenen Anteil einer gerade laufenden Pause (auf den Tagesbeginn begrenzt); total_seconds zählt Pausen nie mit.

Tagesauswertung

GET /api/flowtime/stats/today

Aggregierte Auswertung der heute erfassten Zeiten des Benutzers, einschließlich Pausen und Aufschlüsselung nach Projekt (data.by_project, adressiert über project_uuid).

Wochenauswertung

GET /api/flowtime/stats/week

Aggregierte Auswertung der laufenden Woche mit täglicher Aufschlüsselung und Projekt-Anteilen.

🕐 Arbeitszeiten

Schreibende Balance-Endpoints nur für Teaminhaber und Mitglieder mit FlowTime-Vollzugriff
Die eigene Arbeitszeit-Bilanz kann jedes Mitglied abrufen. Das Anpassen von Überstunden-Salden (POST /working-hours/overtime/adjust) sowie das Ändern der Arbeitszeit-Einstellungen fremder Mitglieder (PUT /working-hours/settings) sind ausschließlich dem Teaminhaber (oder Mitgliedern mit FlowTime-Vollzugriff) vorbehalten.

Arbeitszeit-Status abrufen

GET /api/flowtime/working-hours/status

Ruft die aktuelle Arbeitszeit-Bilanz des angemeldeten Nutzers ab (Tages-, Wochen- und Monatsbilanz sowie Überstunden-Saldo). Sind keine Arbeitszeiten konfiguriert, ist "configured" false.

Arbeitszeit-Einstellungen ändern

PUT /api/flowtime/working-hours/settings

Ändert die Arbeitszeit-Einstellungen eines Teammitglieds (nur Teaminhaber oder Mitglieder mit FlowTime-Vollzugriff). Das Zielmitglied wird über "user_uuid" identifiziert. Nur übergebene Felder werden aktualisiert.

Request Body:

user_uuid string * UUID des Zielmitglieds
weekly_hours number Wochenstunden (0-168)
working_days array Arbeitstage als Zahlen 1-7 (Mo-So)
daily_hours array Sollstunden pro Tag (0-24)
track_overtime boolean Überstunden erfassen
work_time_model string Arbeitszeitmodell: standard, flexible oder shift

Überstunden-Saldo anpassen

POST /api/flowtime/working-hours/overtime/adjust

Passt den Überstunden-Saldo eines Teammitglieds an (nur Teaminhaber oder Mitglieder mit FlowTime-Vollzugriff). Mit "mode" wird der Wert entweder addiert (add, Standard) oder absolut gesetzt (set). Der resultierende Saldo wird serverseitig auf die zulässigen Grenzen begrenzt.

Request Body:

user_uuid string * UUID des Zielmitglieds
minutes integer * Anzahl Minuten (bei mode=add Delta, bei mode=set Zielwert)
mode string add (addieren, Standard) oder set (absolut setzen)
reason string Begründung für den Audit-Trail (max. 500 Zeichen)

Arbeitszeit-Verlauf abrufen

GET /api/flowtime/working-hours/history

Ruft den tagesweisen Arbeitszeit-Verlauf ab. Standardmäßig die aktuelle Woche des angemeldeten Nutzers. Teaminhaber und Mitglieder mit FlowTime-Vollzugriff können über "user_uuid" den Verlauf eines anderen Mitglieds abrufen. Der Zeitraum ist auf maximal 31 Tage begrenzt.

Query-Parameter:

start_date string Startdatum (YYYY-MM-DD, Standard: Wochenanfang)
end_date string Enddatum (YYYY-MM-DD, muss >= start_date sein)
user_uuid string Nur für Teaminhaber (oder Mitglieder mit FlowTime-Vollzugriff): Verlauf eines bestimmten Nutzers

📅 Schichtplanung

Schichtsystem muss aktiviert sein
Alle Schicht-Endpoints setzen voraus, dass das Schichtsystem für das Team aktiviert ist (Team-Einstellung "shifts_enabled"). Ist es deaktiviert, antwortet die API mit HTTP 403.
Berechtigungen: Verwaltung vs. eigene Schichten
Lesende Endpoints (Schichttypen/-vorlagen/-pläne auflisten, eigene Schichten, aktuelle Übersicht, Präferenzen) sowie das Bestätigen/Ablehnen eigener Zuweisungen stehen jedem Mitglied mit FlowTime-Zugriff offen. Verwaltende Aktionen (Anlegen, Ändern, Löschen von Typen/Vorlagen/Plänen/Schichten, Zuweisen und Entfernen von Nutzern, Verfügbarkeitsliste) erfordern das FlowTime-Sub-Recht "schichtplanung"; der Teaminhaber und Mitglieder mit FlowTime-Vollzugriff sind dabei implizit berechtigt. Web-UI und API autorisieren identisch.

Schichttypen auflisten

GET /api/flowtime/shifts/types

Listet alle Schichttypen des Teams auf.

Schichttyp anlegen

POST /api/flowtime/shifts/types

Erstellt einen neuen Schichttyp (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Request Body:

name string * Name des Schichttyps (max. 255 Zeichen)
description string Beschreibung
color string Hex-Farbe (max. 7 Zeichen)
icon string Icon-Kennung (max. 50 Zeichen)
is_active boolean Schichttyp aktiv

Schichttyp abrufen

GET /api/flowtime/shifts/types/{uuid}

Ruft einen einzelnen Schichttyp ab, inklusive der Anzahl seiner Vorlagen und Schichten.

Schichttyp aktualisieren

PUT /api/flowtime/shifts/types/{uuid}

Aktualisiert einen Schichttyp (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Adressierung ausschließlich per UUID.

Request Body:

name string Name des Schichttyps (max. 255 Zeichen)
description string Beschreibung
color string Hex-Farbe im Format #RRGGBB
icon string Icon-Kennung (max. 50 Zeichen)
is_active boolean Schichttyp aktiv

Schichttyp löschen

DELETE /api/flowtime/shifts/types/{uuid}

Löscht einen Schichttyp (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Adressierung ausschließlich per UUID.

Schichtvorlagen auflisten

GET /api/flowtime/shifts/templates

Listet alle Schichtvorlagen des Teams auf.

Schichtvorlage anlegen

POST /api/flowtime/shifts/templates

Erstellt eine neue Schichtvorlage (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Breaking Change: Das frühere numerische Feld "shift_type_id" wird nicht mehr akzeptiert; der Schichttyp wird ausschließlich über "shift_type_uuid" angegeben.

Request Body:

name string * Name der Schichtvorlage (max. 255 Zeichen)
shift_type_uuid string * UUID des Schichttyps (teamgebunden)
start_time string * Startzeit (HH:MM)
end_time string * Endzeit (HH:MM)
min_staff integer Minimale Besetzung
max_staff integer Maximale Besetzung (>= min_staff)
default_days array Standard-Wochentage (1-7)
is_active boolean Schichtvorlage aktiv

Schichtvorlage abrufen

GET /api/flowtime/shifts/templates/{uuid}

Ruft eine einzelne Schichtvorlage samt ihrem Schichttyp ab.

Schichtvorlage aktualisieren

PUT /api/flowtime/shifts/templates/{uuid}

Aktualisiert eine Schichtvorlage (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Adressierung ausschließlich per UUID. Breaking Change: Das frühere numerische Feld "shift_type_id" wird nicht mehr akzeptiert; der Schichttyp wird ausschließlich über "shift_type_uuid" angegeben.

Request Body:

name string Name der Schichtvorlage (max. 255 Zeichen)
shift_type_uuid string UUID des Schichttyps (teamgebunden)
start_time string Startzeit (HH:MM)
end_time string Endzeit (HH:MM)
min_staff integer Minimale Besetzung
max_staff integer Maximale Besetzung (>= min_staff)
default_days array Standard-Wochentage (1-7)
is_active boolean Schichtvorlage aktiv

Schichtvorlage löschen

DELETE /api/flowtime/shifts/templates/{uuid}

Löscht eine Schichtvorlage (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Adressierung ausschließlich per UUID.

Schichtpläne auflisten

GET /api/flowtime/shifts/plans

Listet die Schichtpläne des Teams auf.

Query-Parameter:

status string Filtert nach Status (draft, published oder archived)
start_date string Filtert Pläne ab diesem Datum
end_date string Filtert Pläne bis zu diesem Datum (muss >= start_date sein)

Schichtplan anlegen

POST /api/flowtime/shifts/plans

Erstellt einen neuen Schichtplan für eine Woche (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Breaking Change: Das frühere numerische Feld "shift_type_ids" wird nicht mehr akzeptiert; die Schichttypen werden ausschließlich über "shift_type_uuids" angegeben.

Request Body:

week_start string * Wochenanfang (Datum)
name string Name des Plans (max. 255 Zeichen)
create_from_templates boolean Plan aus Vorlagen erzeugen
shift_type_uuids array UUIDs der zu berücksichtigenden Schichttypen (teamgebunden)
shift_type_uuids.* string Einzelne Schichttyp-UUID

Schichtplan-Details abrufen

GET /api/flowtime/shifts/plans/{uuid}

Ruft einen einzelnen Schichtplan mit seinen Schichten ab. Adressierung ausschließlich per UUID.

Schichtplan ändern

PUT /api/flowtime/shifts/plans/{uuid}

Ändert Name und Notiz eines Schichtplans (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Nur Entwürfe sind änderbar; ein veröffentlichter oder archivierter Plan antwortet mit HTTP 409 und dem Fehler plan_not_editable. Die Planwoche selbst ist unveränderlich, weil die Schichten an ihren Tagen hängen; für eine andere Woche gibt es die Kopieren-Aktion. Der Status ändert sich ausschließlich über publish und archive.

Request Body:

name string Neuer Name des Plans (max. 255 Zeichen)
notes string Notiz zum Plan; null leert sie

Schichtplan löschen

DELETE /api/flowtime/shifts/plans/{uuid}

Löscht einen Schichtplan samt seinen Schichten und deren Zuweisungen (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Nur Entwürfe sind löschbar: ein veröffentlichter Plan ist der Dienstplan, nach dem das Team arbeitet, ein archivierter die Aufzeichnung einer vergangenen Woche. Beide antworten mit HTTP 409 und dem Fehler plan_not_editable und werden stattdessen archiviert.

Schichten eines Plans auflisten

GET /api/flowtime/shifts/plans/{uuid}/shifts

Ruft die Schichten eines Plans seitenweise ab, optional auf einen Tag oder einen Schichttyp eingegrenzt. Die Plan-Detailansicht liefert dagegen die ganze Woche in einer Antwort.

Query-Parameter:

date string Grenzt auf einen Tag ein (YYYY-MM-DD)
shift_type_uuid string Grenzt auf einen Schichttyp des Teams ein
page integer Seitenzahl, ab 1
per_page integer Einträge pro Seite, 1-200 (Standard 50)

Schichtplan veröffentlichen

POST /api/flowtime/shifts/plans/{uuid}/publish

Veröffentlicht einen Schichtplan (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Schichtplan archivieren

POST /api/flowtime/shifts/plans/{uuid}/archive

Archiviert einen Schichtplan (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Schichtplan kopieren

POST /api/flowtime/shifts/plans/{uuid}/copy

Kopiert einen Schichtplan in eine andere Woche (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Request Body:

target_week_start string * Ziel-Wochenstartdatum

Schicht anlegen

POST /api/flowtime/shifts

Erstellt eine einzelne Schicht innerhalb eines Plans (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Breaking Change: Die früheren numerischen Felder "shift_plan_id" und "shift_type_id" werden nicht mehr akzeptiert; Plan und Typ werden ausschließlich über "shift_plan_uuid" und "shift_type_uuid" angegeben.

Request Body:

shift_plan_uuid string * UUID des Schichtplans (teamgebunden)
shift_type_uuid string * UUID des Schichttyps (teamgebunden)
date string * Datum der Schicht
start_time string * Startzeit (HH:MM)
end_time string * Endzeit (HH:MM)
min_staff integer Minimale Besetzung
max_staff integer Maximale Besetzung (>= min_staff)
notes string Notizen zur Schicht

Schicht abrufen

GET /api/flowtime/shifts/{uuid}

Ruft eine einzelne Schicht mit ihren Zuweisungen und ihrem Besetzungsstand ab. Das Feld editable wiederholt die Regel der Planungsoberfläche: nur Schichten in einem Entwurf sind änderbar.

Schicht ändern

PUT /api/flowtime/shifts/{uuid}

Ändert eine Schicht (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Nur Schichten in einem Entwurf sind änderbar, sonst HTTP 409 mit dem Fehler plan_not_editable. Das Datum muss in der Planwoche liegen, sonst HTTP 422 mit date_outside_plan_week. Eine Schicht bleibt in ihrem Plan; für eine andere Woche wird sie im Zielplan neu angelegt. Die Dauer berechnet die Schnittstelle selbst und berücksichtigt dabei Nachtschichten über Mitternacht.

Request Body:

shift_type_uuid string Anderer Schichttyp des Teams
date string Neues Datum (YYYY-MM-DD), muss in der Planwoche liegen
start_time string Beginn im Format HH:MM
end_time string Ende im Format HH:MM
min_staff integer Mindestbesetzung, mindestens 1
max_staff integer Maximalbesetzung; darf die Mindestbesetzung nicht unterschreiten, null hebt die Obergrenze auf
notes string Notiz zur Schicht

Schicht löschen

DELETE /api/flowtime/shifts/{uuid}

Löscht eine Schicht (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff). Adressierung ausschließlich per UUID.

Nutzer einer Schicht zuweisen

POST /api/flowtime/shifts/{uuid}/assign

Weist einer Schicht einen Nutzer zu (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Request Body:

user_uuid string * UUID des zuzuweisenden Nutzers
check_conflicts boolean Zeitliche Konflikte prüfen

Zuweisung entfernen

DELETE /api/flowtime/shifts/{uuid}/assign/{userUuid}

Entfernt die Zuweisung eines Nutzers von einer Schicht (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Verfügbare Nutzer für Schicht

GET /api/flowtime/shifts/{uuid}/available-users

Listet Nutzer, die für eine Schicht zugewiesen werden können (erfordert Sub-Recht "schichtplanung", Teaminhaber oder FlowTime-Vollzugriff).

Zuweisung bestätigen

POST /api/flowtime/shifts/assignments/{uuid}/confirm

Bestätigt eine eigene Schicht-Zuweisung. Steht jedem Mitglied für die eigenen Zuweisungen offen.

Zuweisung ablehnen

POST /api/flowtime/shifts/assignments/{uuid}/decline

Lehnt eine eigene Schicht-Zuweisung ab. Steht jedem Mitglied für die eigenen Zuweisungen offen.

Request Body:

reason string Begründung für die Ablehnung

Eigene Schichten abrufen

GET /api/flowtime/shifts/my-shifts

Ruft die eigenen Schichten des angemeldeten Nutzers ab.

Query-Parameter:

start_date string Filtert Schichten ab diesem Datum
end_date string Filtert Schichten bis zu diesem Datum (muss >= start_date sein)

Aktuelle Schicht-Übersicht

GET /api/flowtime/shifts/current

Ruft die aktuelle Schicht-Übersicht ab.

Eigene Verfügbarkeits-Präferenzen

GET /api/flowtime/shifts/preferences

Ruft die eigenen Verfügbarkeits-Präferenzen des angemeldeten Nutzers ab.

Verfügbarkeits-Präferenz setzen

PUT /api/flowtime/shifts/preferences/{dayOfWeek}

Setzt die eigene Verfügbarkeits-Präferenz für einen Wochentag (1-7). Steht jedem Mitglied für die eigenen Präferenzen offen.

Request Body:

availability string * Verfügbarkeit: available, preferred, unavailable oder if_needed
available_from string Verfügbar ab (HH:MM)
available_until string Verfügbar bis (HH:MM)
preferred_shift_types array Bevorzugte Schichttypen als UUIDs (teamgebunden)
notes string Notizen (max. 500 Zeichen)

Stempeluhr-Zustandsmaschine (Einfache Zeiterfassung)

Im Modus "Einfache Zeiterfassung" (Team-Einstellung) wird der Zustand allein aus dem einzigen offenen Zeiteintrag abgeleitet. Pro Benutzer existiert höchstens ein offener Eintrag (DB-erzwungen).

Von Status Mögliche Folgestatus
clocked_out working
working on_break, clocked_out
on_break working, clocked_out