{ "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": "Bewertete Arbeitszeit pro Mitarbeiter und Tag, nach denselben Regeln wie die TimeMonkey-App. Nur Tage mit Stempeln oder geplanten Schichten; Zeitraum höchstens 92 Tage und nicht in der Zukunft. Monatssalden sind nicht enthalten.", "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" }, "workedMs": { "type": "number", "description": "Bewertete Arbeitszeit nach Pausen, gesetzlichem Pausenabzug und Arbeitszeitpauschale; die Arbeitszeitpauschale (dailyDeductionMs) ist bereits enthalten" }, "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" } }, "required": [ "date", "employeeId", "workedMs", "breakMs", "legalBreakMs", "plannedMs", "start", "end", "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" } } } } } } } }, "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 } } } }