{"openapi":"3.0.3","info":{"title":"Zeiterfassung REST-API","version":"1.0.0","description":"Schnittstelle für externe Systeme (Lohnabrechnung, Schichtplanung, Dashboards). Authentifizierung mit einem in der Verwaltung erzeugten API-Schlüssel: `Authorization: Bearer zk_…`. Zeitpunkte sind ISO-8601 in UTC, Datumsangaben lokale Kalendertage (JJJJ-MM-TT). Die Anfragerate ist je Schlüssel begrenzt (Standard 120/Minute, Antwort 429)."},"servers":[{"url":"http://zeiterfassung.ciogastro.de"}],"security":[{"ApiKey":[]}],"paths":{"/api/v1/branches":{"get":{"summary":"Filialen auflisten","description":"Alle nicht gelöschten Filialen. Recht: `read`.","security":[{"ApiKey":["read"]}],"responses":{"200":{"description":"Filialen","content":{"application/json":{"schema":{"type":"object","properties":{"branches":{"type":"array","items":{"$ref":"#/components/schemas/Branch"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/employees":{"get":{"summary":"Mitarbeiter auflisten","description":"Recht: `read`. PINs werden nie ausgegeben.","security":[{"ApiKey":["read"]}],"parameters":[{"name":"status","in":"query","description":"active (Standard), inactive oder all","schema":{"type":"string","enum":["active","inactive","all"]}},{"name":"personnelNumber","in":"query","description":"Genau diese Personalnummer","schema":{"type":"string"}},{"name":"branchId","in":"query","description":"Heimatfiliale (Id) oder `none` für Mitarbeiter ohne Filiale","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximal 1000, Standard 500","schema":{"type":"integer"}},{"name":"offset","in":"query","description":"Überspringen (Seitenweise Abruf)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Mitarbeiter","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"employees":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"summary":"Mitarbeiter anlegen","description":"Recht: `employees:write`. Ohne `personnelNumber` wird die nächste freie Nummer des Filial-Präfixes vergeben (Präfix 200 → 201, 202 …). Es wird automatisch eine eindeutige 5-stellige PIN erzeugt, die **nur in dieser Antwort** steht. Das Anlegen kann bei vielen Mitarbeitern einige Sekunden dauern (Eindeutigkeitsprüfung der PIN).","security":[{"ApiKey":["employees:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreate"}}}},"responses":{"201":{"description":"Angelegt","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"},"employee":{"$ref":"#/components/schemas/Employee"},"pin":{"type":"string","example":"48213"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Personalnummer bereits vergeben","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/employees/{id}":{"get":{"summary":"Mitarbeiter abrufen","security":[{"ApiKey":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Interne Id des Mitarbeiters (nicht die Personalnummer).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Mitarbeiter","content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"$ref":"#/components/schemas/Employee"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"summary":"Mitarbeiter ändern","description":"Recht: `employees:write`. Nur die gesendeten Felder werden geändert. Die Personalnummer ist unveränderlich; Mitarbeiter werden nie gelöscht, sondern mit `active: false` deaktiviert (Buchungen bleiben erhalten). `branchId: null` entfernt die Heimatfiliale. Die PIN lässt sich über die API nicht ändern.","security":[{"ApiKey":["employees:write"]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Interne Id des Mitarbeiters (nicht die Personalnummer).","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeUpdate"}}}},"responses":{"200":{"description":"Geändert","content":{"application/json":{"schema":{"type":"object","properties":{"employee":{"$ref":"#/components/schemas/Employee"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/time-entries":{"get":{"summary":"Einzelbuchungen","description":"Neueste zuerst. Recht: `read`.","security":[{"ApiKey":["read"]}],"parameters":[{"name":"from","in":"query","description":"Erstes Datum (JJJJ-MM-TT, lokales Kalenderdatum der Buchung)","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Letztes Datum (JJJJ-MM-TT, einschließlich)","schema":{"type":"string","format":"date"}},{"name":"employeeId","in":"query","description":"Nur Buchungen dieses Mitarbeiters","schema":{"type":"integer"}},{"name":"branchId","in":"query","description":"Nur Buchungen an diesem Standort","schema":{"type":"integer"}},{"name":"homeBranchId","in":"query","description":"Nur Mitarbeiter mit dieser Heimatfiliale (zum Buchungszeitpunkt)","schema":{"type":"integer"}},{"name":"limit","in":"query","description":"Maximal 5000, Standard 1000","schema":{"type":"integer"}},{"name":"offset","in":"query","description":"Überspringen","schema":{"type":"integer"}}],"responses":{"200":{"description":"Buchungen","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/TimeEntry"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/work-sessions":{"get":{"summary":"Arbeitszeiten (gepaarte Schichten) mit Summen je Mitarbeiter","description":"Aus den Buchungen des Zeitraums gebildete Schichten inkl. Pausen und Netto-Arbeitszeit. Netto = Ende − Beginn − Pause. Ist eine Schicht über der Schwelle (Standard 6 h), wird die Pause auf mindestens 60 Min. angehoben (`breakAssumed`); eine längere gebuchte Pause wird vollständig abgezogen. Schichten, die über die Zeitraumgrenzen hinausreichen, erscheinen nur mit den Buchungen innerhalb des Zeitraums. `totals` zählt nur abgeschlossene Schichten. Recht: `read`.","security":[{"ApiKey":["read"]}],"parameters":[{"name":"from","in":"query","description":"Erstes Datum (JJJJ-MM-TT, lokales Kalenderdatum der Buchung)","schema":{"type":"string","format":"date"},"required":true},{"name":"to","in":"query","description":"Letztes Datum (JJJJ-MM-TT, einschließlich)","schema":{"type":"string","format":"date"},"required":true},{"name":"employeeId","in":"query","description":"Nur Buchungen dieses Mitarbeiters","schema":{"type":"integer"}},{"name":"branchId","in":"query","description":"Nur Buchungen an diesem Standort","schema":{"type":"integer"}},{"name":"homeBranchId","in":"query","description":"Nur Mitarbeiter mit dieser Heimatfiliale (zum Buchungszeitpunkt)","schema":{"type":"integer"}}],"responses":{"200":{"description":"Arbeitszeiten","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/WorkSession"}},"totals":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeTotal"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/v1/presence":{"get":{"summary":"Aktuell anwesende Mitarbeiter","security":[{"ApiKey":["read"]}],"parameters":[{"name":"branchId","in":"query","description":"Nur Mitarbeiter dieser Heimatfiliale","schema":{"type":"integer"}}],"responses":{"200":{"description":"Anwesende","content":{"application/json":{"schema":{"type":"object","properties":{"present":{"type":"array","items":{"$ref":"#/components/schemas/Presence"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"API-Schlüssel aus Verwaltung → API-Zugriff, z. B. `zk_AbC…`"}},"responses":{"BadRequest":{"description":"Ungültige Anfrage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Dem Schlüssel fehlt das nötige Recht","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate-Limit überschritten","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"Unbekannte Filiale."},"code":{"type":"string","example":"BRANCH_UNKNOWN"}}},"Branch":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address":{"type":"string","nullable":true},"active":{"type":"boolean"},"personnelPrefix":{"type":"integer","nullable":true,"description":"Präfix der automatischen Personalnummern (200 → 201–299)"}}},"Employee":{"type":"object","properties":{"id":{"type":"integer"},"personnelNumber":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"branchId":{"type":"integer","nullable":true,"description":"Heimatfiliale; null = ohne Filiale"},"branchName":{"type":"string","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"EmployeeCreate":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string","maxLength":80},"lastName":{"type":"string","maxLength":80},"email":{"type":"string","format":"email"},"personnelNumber":{"type":"string","description":"1–32 Zeichen (Buchstaben, Ziffern, . _ -); leer = automatisch"},"branchId":{"type":"integer","description":"Heimatfiliale – `branchId` oder `branchName` ist Pflicht"},"branchName":{"type":"string"}}},"EmployeeUpdate":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","description":"Leerer Text löscht die E-Mail"},"branchId":{"type":"integer","nullable":true},"branchName":{"type":"string"},"active":{"type":"boolean"}}},"TimeEntry":{"type":"object","properties":{"id":{"type":"integer"},"employeeId":{"type":"integer"},"personnelNumber":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["start","break_start","break_end","end"]},"label":{"type":"string","example":"Arbeitsbeginn"},"occurredAt":{"type":"string","format":"date-time"},"date":{"type":"string","format":"date"},"time":{"type":"string","example":"08:15"},"locationBranchId":{"type":"integer","description":"Standort der Buchung"},"locationName":{"type":"string"},"homeBranchId":{"type":"integer","description":"Heimatfiliale zum Buchungszeitpunkt"},"homeBranchName":{"type":"string"},"deviceName":{"type":"string","nullable":true},"source":{"type":"string","enum":["kiosk","korrektur","auto"]},"note":{"type":"string","nullable":true}}},"WorkSession":{"type":"object","properties":{"employeeId":{"type":"integer"},"personnelNumber":{"type":"string"},"name":{"type":"string"},"date":{"type":"string","format":"date"},"startedAt":{"type":"string","format":"date-time","nullable":true},"endedAt":{"type":"string","format":"date-time","nullable":true},"minutes":{"type":"integer","nullable":true,"description":"Brutto-Dauer"},"breakMinutes":{"type":"integer"},"breakAssumed":{"type":"boolean","description":"Pause wurde automatisch angenommen (keine gebucht)"},"netMinutes":{"type":"integer","nullable":true,"description":"Dauer abzüglich Pause"},"status":{"type":"string","enum":["vollstaendig","offen","ohne-beginn"]},"homeBranchName":{"type":"string"},"locationName":{"type":"string","description":"Standort(e) der Schicht, z. B. „A → B“"}}},"EmployeeTotal":{"type":"object","properties":{"employeeId":{"type":"integer"},"personnelNumber":{"type":"string"},"name":{"type":"string"},"sessions":{"type":"integer"},"netMinutes":{"type":"integer"}}},"Presence":{"type":"object","properties":{"employeeId":{"type":"integer"},"personnelNumber":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["working","break"]},"since":{"type":"string","format":"date-time"},"homeBranchName":{"type":"string","nullable":true},"locationName":{"type":"string"}}}}}}