{"openapi":"3.0.3","info":{"title":"TimeMonkey REST-API (Beta)","version":"1.0.0-beta.1","description":"Lesender Zugriff auf die Daten eines Standorts. Enthalten in TimeMonkey PRO.\n\nBeta: Endpunkte und Felder können sich bis zur Version 1.0.0 noch ändern. Doku: https://docs.time.monkeymed.de/docs/api\n\nAuthentifizierung: `Authorization: Bearer tmk_live_…` (API-Key aus Einstellungen → Schnittstellen). Scopes: employees:read, stamps:read, absences:read, shifts:read, evaluations:read.\n\nLimits pro Key: 60 Requests pro Minute und 1000 pro Tag.\n\nIDs sind 24-stellige Hex-Strings, Zeitpunkte ISO-8601 in UTC, Datumsfilter YYYY-MM-DD in Europe/Berlin, Dauern in Millisekunden."},"servers":[{"url":"https://api.time.monkeymed.de"}],"security":[{"apiKey":[]}],"paths":{"/api/v1/company":{"get":{"operationId":"getCompany","tags":["Firma"],"summary":"Standort des API-Keys","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"nullable":true,"description":"Aktuell gültige Standortadresse","type":"object","properties":{"street":{"nullable":true,"type":"string"},"streetNo":{"nullable":true,"type":"string"},"zip":{"nullable":true,"type":"string"},"city":{"nullable":true,"type":"string"},"province":{"nullable":true,"type":"string"},"country":{"nullable":true,"type":"string"}},"required":["street","streetNo","zip","city","province","country"],"additionalProperties":false},"timeZone":{"type":"string","enum":["Europe/Berlin"]}},"required":["id","name","address","timeZone"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/employees":{"get":{"operationId":"listEmployees","tags":["Mitarbeiter"],"summary":"Mitarbeiter auflisten","x-required-scope":"employees:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"default":"active","type":"string","enum":["active","inactive","all"]}},{"name":"include","in":"query","required":false,"description":"`contractHistory` liefert zusätzlich alle Vertragsstände","schema":{"description":"`contractHistory` liefert zusätzlich alle Vertragsstände","type":"string","enum":["contractHistory"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"prename":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"employedSince":{"nullable":true,"type":"string"},"employedUntil":{"nullable":true,"type":"string"},"mail":{"nullable":true,"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"mainTag":{"nullable":true,"type":"string"},"contract":{"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["weeklyHours","monthlyHours",null]},"weeklyMs":{"nullable":true,"description":"Wochenstunden; ohne positiven Wochenwert Summe der Tageswerte (außer bei Monatsverträgen)","type":"number"},"monthlyMs":{"nullable":true,"type":"number"},"dailyMs":{"nullable":true,"type":"object","properties":{"mon":{"nullable":true,"type":"number"},"tue":{"nullable":true,"type":"number"},"wed":{"nullable":true,"type":"number"},"thu":{"nullable":true,"type":"number"},"fri":{"nullable":true,"type":"number"},"sat":{"nullable":true,"type":"number"},"sun":{"nullable":true,"type":"number"}},"required":["mon","tue","wed","thu","fri","sat","sun"],"additionalProperties":false},"annualVacationDays":{"nullable":true,"type":"number"},"dailyDeductionMs":{"nullable":true,"description":"Arbeitszeitpauschale: zur bewerteten Arbeitszeit (workedMs) nur bei vollständigen Tagen mit positiver Nettoarbeitszeit addiert, bei negativem Wert abgezogen; workedMs bleibt mindestens 0. In der Planzeit (plannedMs) bei vorhandener Schicht unabhängig von Stempeln und Nettoarbeitszeit berücksichtigt","type":"number"}},"required":["type","weeklyMs","monthlyMs","dailyMs","annualVacationDays","dailyDeductionMs"],"additionalProperties":false,"description":"Zum Abfragezeitpunkt gültige Vertragswerte (Zeiten in Millisekunden)"},"contractHistory":{"description":"Nur mit `include=contractHistory`","type":"object","properties":{"dailyHours":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"type":"object","properties":{"mon":{"nullable":true,"type":"number"},"tue":{"nullable":true,"type":"number"},"wed":{"nullable":true,"type":"number"},"thu":{"nullable":true,"type":"number"},"fri":{"nullable":true,"type":"number"},"sat":{"nullable":true,"type":"number"},"sun":{"nullable":true,"type":"number"},"type":{"nullable":true,"type":"string","enum":["weeklyHours","monthlyHours",null]},"monthlyMs":{"nullable":true,"type":"number"}},"required":["mon","tue","wed","thu","fri","sat","sun","type","monthlyMs"],"additionalProperties":false}},"required":["validFrom","value"],"additionalProperties":false}},"weeklyMs":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false},"description":"Wirksame Wochenwerte an Änderungszeitpunkten von Wochen- und Tageswerten; gleicher Fallback wie contract.weeklyMs"},"monthlyMs":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false}},"annualVacationDays":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false}},"dailyDeductionMs":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false}}},"required":["dailyHours","weeklyMs","monthlyMs","annualVacationDays","dailyDeductionMs"],"additionalProperties":false}},"required":["id","prename","name","status","employedSince","employedUntil","mail","tags","mainTag","contract"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/employees/{id}":{"get":{"operationId":"getEmployee","tags":["Mitarbeiter"],"summary":"Einen Mitarbeiter abrufen","x-required-scope":"employees:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"include","in":"query","required":false,"description":"`contractHistory` liefert zusätzlich alle Vertragsstände","schema":{"description":"`contractHistory` liefert zusätzlich alle Vertragsstände","type":"string","enum":["contractHistory"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"prename":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"employedSince":{"nullable":true,"type":"string"},"employedUntil":{"nullable":true,"type":"string"},"mail":{"nullable":true,"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"mainTag":{"nullable":true,"type":"string"},"contract":{"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["weeklyHours","monthlyHours",null]},"weeklyMs":{"nullable":true,"description":"Wochenstunden; ohne positiven Wochenwert Summe der Tageswerte (außer bei Monatsverträgen)","type":"number"},"monthlyMs":{"nullable":true,"type":"number"},"dailyMs":{"nullable":true,"type":"object","properties":{"mon":{"nullable":true,"type":"number"},"tue":{"nullable":true,"type":"number"},"wed":{"nullable":true,"type":"number"},"thu":{"nullable":true,"type":"number"},"fri":{"nullable":true,"type":"number"},"sat":{"nullable":true,"type":"number"},"sun":{"nullable":true,"type":"number"}},"required":["mon","tue","wed","thu","fri","sat","sun"],"additionalProperties":false},"annualVacationDays":{"nullable":true,"type":"number"},"dailyDeductionMs":{"nullable":true,"description":"Arbeitszeitpauschale: zur bewerteten Arbeitszeit (workedMs) nur bei vollständigen Tagen mit positiver Nettoarbeitszeit addiert, bei negativem Wert abgezogen; workedMs bleibt mindestens 0. In der Planzeit (plannedMs) bei vorhandener Schicht unabhängig von Stempeln und Nettoarbeitszeit berücksichtigt","type":"number"}},"required":["type","weeklyMs","monthlyMs","dailyMs","annualVacationDays","dailyDeductionMs"],"additionalProperties":false,"description":"Zum Abfragezeitpunkt gültige Vertragswerte (Zeiten in Millisekunden)"},"contractHistory":{"description":"Nur mit `include=contractHistory`","type":"object","properties":{"dailyHours":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"type":"object","properties":{"mon":{"nullable":true,"type":"number"},"tue":{"nullable":true,"type":"number"},"wed":{"nullable":true,"type":"number"},"thu":{"nullable":true,"type":"number"},"fri":{"nullable":true,"type":"number"},"sat":{"nullable":true,"type":"number"},"sun":{"nullable":true,"type":"number"},"type":{"nullable":true,"type":"string","enum":["weeklyHours","monthlyHours",null]},"monthlyMs":{"nullable":true,"type":"number"}},"required":["mon","tue","wed","thu","fri","sat","sun","type","monthlyMs"],"additionalProperties":false}},"required":["validFrom","value"],"additionalProperties":false}},"weeklyMs":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false},"description":"Wirksame Wochenwerte an Änderungszeitpunkten von Wochen- und Tageswerten; gleicher Fallback wie contract.weeklyMs"},"monthlyMs":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false}},"annualVacationDays":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false}},"dailyDeductionMs":{"type":"array","items":{"type":"object","properties":{"validFrom":{"type":"string"},"value":{"nullable":true,"type":"number"}},"required":["validFrom","value"],"additionalProperties":false}}},"required":["dailyHours","weeklyMs","monthlyMs","annualVacationDays","dailyDeductionMs"],"additionalProperties":false}},"required":["id","prename","name","status","employedSince","employedUntil","mail","tags","mainTag","contract"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stamps":{"get":{"operationId":"listStamps","tags":["Stempel"],"summary":"Stempelzeiten auflisten","description":"Sichtbare Stempel im Zeitraum `from`–`to` (inklusive, höchstens 366 Tage), aufsteigend nach Zeitpunkt.","x-required-scope":"stamps:read","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"employeeId":{"type":"string"},"timestamp":{"type":"string"},"sourceType":{"type":"string","enum":["web","app","correction","unknown"],"description":"`web` = Web-App, `app` = TimeMonkey-App/Terminal, `correction` = aus genehmigtem Änderungsantrag"}},"required":["id","employeeId","timestamp","sourceType"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/absences":{"get":{"operationId":"listAbsences","tags":["Abwesenheiten"],"summary":"Abwesenheiten (Urlaub, Krankheit, …) auflisten","description":"Liefert alle Abwesenheiten, die den Zeitraum `from`–`to` (inklusive) berühren.","x-required-scope":"absences:read","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["Sickness","ChildSickness","Vacation","ShortTimeWork","CompensatoryTimeOff","FurtherEducation","ProfessionalSchool","Holiday","MaternityProtection","ParentalLeave"]}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"employeeId":{"type":"string"},"type":{"type":"string","enum":["Sickness","ChildSickness","Vacation","ShortTimeWork","CompensatoryTimeOff","FurtherEducation","ProfessionalSchool","Holiday","MaternityProtection","ParentalLeave"]},"start":{"type":"string"},"end":{"type":"string"},"paid":{"nullable":true,"type":"boolean"},"name":{"nullable":true,"description":"Freitext-Bezeichnung, falls vergeben","type":"string"},"status":{"type":"string","enum":["approved","requested","rejected","cancellation_requested","cancelled"]},"halfDays":{"type":"array","items":{"type":"string"},"description":"Tage (YYYY-MM-DD, Europe/Berlin), die nur halb zählen"}},"required":["id","employeeId","type","start","end","paid","name","status","halfDays"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/shifts":{"get":{"operationId":"listShifts","tags":["Schichtplanung"],"summary":"Veröffentlichte Schichten auflisten","description":"Schichten aus veröffentlichten Wochenplänen mit Beginn im Zeitraum `from`–`to` (inklusive, höchstens 366 Tage). Archivierte Pläne und Schichten verbundener Standorte fehlen.","x-required-scope":"shifts:read","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"weekplanId":{"type":"string"},"start":{"type":"string"},"end":{"type":"string"},"breaks":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":false}},"areaId":{"nullable":true,"type":"string"},"areaName":{"nullable":true,"type":"string"},"serviceName":{"nullable":true,"type":"string"},"employeeIds":{"type":"array","items":{"type":"string"}}},"required":["id","weekplanId","start","end","breaks","areaId","areaName","serviceName","employeeIds"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/areas":{"get":{"operationId":"listAreas","tags":["Schichtplanung"],"summary":"Arbeitsbereiche auflisten","x-required-scope":"shifts:read","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"hidden":{"type":"boolean","description":"In der Planung ausgeblendet"}},"required":["id","name","hidden"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/evaluations/days":{"get":{"operationId":"listEvaluationDays","tags":["Auswertungen"],"summary":"Tagesauswertung je Mitarbeiter","description":"Tageswerte der Monatsauswertung pro Mitarbeiter, berechnet mit derselben Logik wie die TimeMonkey-App: Soll, Arbeitszeit, Gutschriften, abgegoltene Überstunden und Tagessaldo. Nur Tage mit Soll, Arbeitszeit, Stempeln, Schichten oder Abwesenheiten; Zeitraum höchstens 92 Tage und nicht in der Zukunft. Monatssalden und Kontostand: /evaluations/months. Rechenintensiv: Eine Seite endet nach einem Rechenbudget auch mit weniger als `limit` Zeilen, maßgeblich ist `nextCursor`.","x-required-scope":"evaluations:read","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"YYYY-MM-DD, Europe/Berlin"},"employeeId":{"type":"string"},"contractMs":{"type":"number","description":"Vertragliche Arbeitszeit des Tages (Spalte „Vertragliche Arbeitszeit“)"},"workedMs":{"type":"number","description":"Bewertete Arbeitszeit (Spalte „Arbeitszeit“) nach Pausen, gesetzlichem Pausenabzug, Start-/Endzeit-Begrenzung und Arbeitszeitpauschale; die Arbeitszeitpauschale (dailyDeductionMs) ist bereits enthalten. An Feiertagen je nach Feiertagsmodus der Firma"},"creditMs":{"type":"number","description":"Summe der bezahlten Gutschriften (Feiertag, Krankheit, Urlaub, …)"},"compensatedOvertimeMs":{"type":"number","description":"Vertraglich abgegoltene Überstunden nach der Tagesregel; die Monatsregel steht nur in /evaluations/months"},"balanceMs":{"type":"number","description":"Tagessaldo = workedMs + creditMs − contractMs − compensatedOvertimeMs"},"dailyDeductionMs":{"type":"number","description":"Angewandte Arbeitszeitpauschale; 0 an Tagen ohne Arbeitszeit"},"breakMs":{"type":"number"},"legalBreakMs":{"type":"number","description":"Abzug für gesetzliche Pausen"},"plannedMs":{"type":"number","description":"Geplante Arbeitszeit laut veröffentlichtem Schichtplan (auch verbundener Standorte) nach Arbeitszeitpauschale und gesetzlichem Pausenabzug"},"start":{"nullable":true,"type":"string"},"end":{"nullable":true,"type":"string"},"incomplete":{"type":"boolean","description":"Ungerade Stempelzahl; der Tag ist noch nicht auswertbar"},"holiday":{"nullable":true,"description":"Feiertag am Standort bzw. eingetragener Feiertag","type":"object","properties":{"name":{"nullable":true,"type":"string"}},"required":["name"],"additionalProperties":false},"absences":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Sickness","ChildSickness","Vacation","ShortTimeWork","CompensatoryTimeOff","FurtherEducation","ProfessionalSchool","Holiday","MaternityProtection","ParentalLeave"]},"paid":{"type":"boolean"},"durationMs":{"type":"number","description":"Stunden des Eintrags an diesem Tag; bei bezahlten Einträgen ist das die Gutschrift"},"days":{"type":"number","description":"1 oder 0.5 (halber Tag)"}},"required":["type","paid","durationMs","days"],"additionalProperties":false},"description":"Abwesenheiten und Gutschriften des Tages (Spalte „Sonstiges“), nur genehmigte"},"accountPaused":{"type":"boolean","description":"Elternzeit mit pausiertem Arbeitszeitkonto; alle Stundenwerte sind 0"}},"required":["date","employeeId","contractMs","workedMs","creditMs","compensatedOvertimeMs","balanceMs","dailyDeductionMs","breakMs","legalBreakMs","plannedMs","start","end","incomplete","holiday","absences","accountPaused"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/evaluations/months":{"get":{"operationId":"listEvaluationMonths","tags":["Auswertungen"],"summary":"Monatssaldo und Arbeitszeitkonto je Mitarbeiter","description":"Monatswerte wie in der Monatsauswertung der TimeMonkey-App: Soll, Gutschriften, Arbeitszeit, Korrektur, abgegoltene Überstunden (Tages- und Monatsregel), Monatssaldo und laufendes Arbeitszeitkonto inklusive Jahresübertrag. Höchstens 12 Monate, nicht in der Zukunft; der laufende Monat zählt bis heute. Nur Monate, in denen der Mitarbeiter ausgewertet wird (ab Vertragsbeginn, bis Austritt). Rechenintensiv: Eine Seite endet nach einem Rechenbudget auch mit weniger als `limit` Zeilen, maßgeblich ist `nextCursor`.","x-required-scope":"evaluations:read","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM"},"employeeId":{"type":"string"},"through":{"type":"string","description":"Letzter eingerechneter Tag (YYYY-MM-DD); im laufenden Monat heute"},"contractMs":{"type":"number","description":"Vertragliche Arbeitszeit"},"creditMs":{"type":"number","description":"Bezahlte Gutschriften (Feiertage, Krankheit, Urlaub, …)"},"targetMs":{"type":"number","description":"Soll = contractMs − creditMs"},"workedMs":{"type":"number","description":"Bewertete Arbeitszeit"},"plannedMs":{"type":"number","description":"Geplante Arbeitszeit laut Schichtplan"},"correctionMs":{"type":"number","description":"Manuelle Monatskorrektur"},"compensatedOvertimeMs":{"type":"number","description":"Vertraglich abgegoltene Überstunden: Summe der Tagesregel plus Monatsregel"},"balanceMs":{"type":"number","description":"Monatssaldo (Über-/Minusstunden) = workedMs + correctionMs − targetMs − compensatedOvertimeMs"},"accountMs":{"type":"number","description":"Arbeitszeitkonto am Ende von `through` wie in der Monatsauswertung: Übertrag aus dem Vorjahr plus Salden des Jahres bis einschließlich dieses Monats"},"incomplete":{"type":"boolean","description":"Mindestens ein Tag mit ungerader Stempelzahl"}},"required":["month","employeeId","through","contractMs","creditMs","targetMs","workedMs","plannedMs","correctionMs","compensatedOvertimeMs","balanceMs","accountMs","incomplete"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/evaluations/years":{"get":{"operationId":"listEvaluationYears","tags":["Auswertungen"],"summary":"Jahreskonto und Urlaubskonto je Mitarbeiter","description":"Stundenübertrag aus dem Vorjahr, Über-/Minusstunden des Jahres, Arbeitszeitkonto und Urlaubskonto (Anspruch, Resturlaub mit Verfall, genommen, geplant, verfügbar) wie in der Jahresauswertung der TimeMonkey-App. Das laufende Jahr zählt bis heute. Rechenintensiv: Eine Seite endet nach einem Rechenbudget auch mit weniger als `limit` Zeilen, maßgeblich ist `nextCursor`.","x-required-scope":"evaluations:read","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","minimum":2000,"maximum":9007199254740991}},{"name":"employeeId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"year":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"employeeId":{"type":"string"},"through":{"type":"string","description":"Letzter eingerechneter Tag (YYYY-MM-DD); im laufenden Jahr heute"},"carryoverMs":{"type":"number","description":"Stundenübertrag aus dem Vorjahr"},"balanceMs":{"type":"number","description":"Über-/Minusstunden des Jahres bis `through` (Summe der Monatssalden)"},"accountMs":{"type":"number","description":"Arbeitszeitkonto am Ende von `through` = carryoverMs + balanceMs"},"vacation":{"type":"object","properties":{"annualDays":{"type":"number","description":"Jahresanspruch"},"carryoverDays":{"type":"number","description":"Resturlaub aus dem Vorjahr"},"carryoverExpiresOn":{"nullable":true,"description":"Verfallsdatum des Resturlaubs (YYYY-MM-DD) oder null","type":"string"},"usedDays":{"type":"number","description":"Genommen (bis heute) aus dem Jahresanspruch"},"usedCarryoverDays":{"type":"number","description":"Genommen (bis heute) aus dem Resturlaub"},"scheduledDays":{"type":"number","description":"Geplant (ab morgen) aus dem Jahresanspruch"},"scheduledCarryoverDays":{"type":"number","description":"Geplant (ab morgen) aus dem Resturlaub"},"availableDays":{"type":"number","description":"Noch verfügbar aus dem Jahresanspruch"},"availableCarryoverDays":{"type":"number","description":"Noch verfügbarer Resturlaub (0 nach Verfall)"}},"required":["annualDays","carryoverDays","carryoverExpiresOn","usedDays","usedCarryoverDays","scheduledDays","scheduledCarryoverDays","availableDays","availableCarryoverDays"],"additionalProperties":false,"description":"Urlaubskonto wie in der App (Urlaub, Jahresauswertung); Tage, auf 0,01 gerundet"}},"required":["year","employeeId","through","carryoverMs","balanceMs","accountMs","vacation"],"additionalProperties":false}},"nextCursor":{"nullable":true,"description":"Für die nächste Seite als `cursor` übergeben; null = Ende","type":"string"}},"required":["data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden_scope`, `license_required`, `payment_locked` oder `company_pending_review`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"`method_not_allowed`, Allow: GET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`, siehe `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`internal`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"tmk_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden_scope","license_required","payment_locked","company_pending_review","validation_error","not_found","method_not_allowed","rate_limited","internal"]},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}