{ "openapi": "3.1.0", "info": { "title": "Tiveo API", "version": "1.0.0-beta", "summary": "Beschäftigte, Abwesenheiten, Zeiten und Schichten aus Tiveo lesen (Beta).", "description": "Die öffentliche API von Tiveo, ab dem Paket Business. **Beta**: nur Lesen; Schreiben ist geplant. Dokumentation: https://tiveo.de/entwickler/", "contact": { "name": "Tiveo", "email": "info@tiveo.de", "url": "https://tiveo.de/entwickler/" }, "termsOfService": "https://tiveo.de/agb/", "x-beta": true }, "servers": [ { "url": "https://api.tiveo.de/v1" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Schlüssel prüfen", "description": "Unternehmen, Rechte und Grenzen dieses Schlüssels — der erste Aufruf jeder Anbindung." }, { "name": "Beschäftigte", "description": "Alle Beschäftigten des Unternehmens, auch Stammsätze ohne Konto und Ausgetretene. Ohne Beispielpersonen und Verwaltungskonten." }, { "name": "Einheiten", "description": "Bereiche, Abteilungen, Teams und Standorte als Baum (`parent_id`), mit Leitung." }, { "name": "Abwesenheitsarten", "description": "Urlaub, Krankheit, Homeoffice und eigene Arten des Unternehmens." }, { "name": "Abwesenheiten", "description": "Anträge und eingetragene Abwesenheiten, ohne Entwürfe und ohne Freitext. Ohne absences:read_sensitive sind sensible Arten maskiert (`masked: true`, `type_id: null`)." }, { "name": "Urlaubsstände", "description": "Je Person und Jahr Anspruch, genommen, beantragt, Rest und Übertrag — live gerechnet wie in der App. Geblättert wird nach Personen." }, { "name": "Feiertage und freie Tage", "description": "Gesetzliche Feiertage (nach Land und Region) und freie Tage des Betriebs eines Jahres, nach Datum. Ohne Blättern." }, { "name": "Stempelungen", "description": "Kommen, Gehen und Pausen, wie sie gelten: ohne aufgehobene und ersetzte Buchungen. Zeitraum höchstens 93 Tage." }, { "name": "Tageswerte", "description": "Je Person und Tag Arbeit, Pause, Soll und Saldo in Minuten — gerechnet wie „Meine Zeiten“. Zeitraum höchstens 62 Tage; `limit` zählt Personen (Vorgabe 10, höchstens 25)." }, { "name": "Projekte", "description": "Projekte, auf die Beschäftigte Zeit buchen." }, { "name": "Projektzeiten", "description": "Gebuchte Minuten je Person, Tag und Projekt. Zeitraum höchstens 93 Tage." }, { "name": "Schichtarten", "description": "Früh, Spät, Bereitschaft und weitere Arten mit Zeiten." }, { "name": "Schichten", "description": "Veröffentlichte Schichten, auch ausgefallene und abgesagte; keine Entwürfe, keine Notizen. Zeitraum höchstens 93 Tage." }, { "name": "Fahrzeuge", "description": "Firmenfahrzeuge (Pool und Dienstwagen) und eigene Autos von Beschäftigten für Kilometergeld, auch ausgemusterte." }, { "name": "Fahrten", "description": "Fahrten in ihrer gültigen Fassung, ohne aufgehobene. Privatfahrt und Arbeitsweg nur mit Tag und Kilometern. Geschützte Geschäftspartner nur als Nummer. Nie die Route. Zeitraum höchstens 93 Tage." }, { "name": "Fahrzeugkosten", "description": "Kosten je Fahrzeug, ohne Notiz und ohne Beleg (nur ob es einen gibt). Zeitraum höchstens 366 Tage." }, { "name": "Kilometergeld", "description": "Freigegebenes Kilometergeld für betriebliche Fahrten mit dem eigenen Auto: die jüngste Fassung je Person und Monat." }, { "name": "Schreiben (geplant)", "description": "In der Beta gesperrt." } ], "paths": { "/me": { "get": { "operationId": "list_me", "summary": "Schlüssel prüfen", "description": "Unternehmen, Rechte und Grenzen dieses Schlüssels — der erste Aufruf jeder Anbindung.", "tags": [ "Schlüssel prüfen" ], "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/employees": { "get": { "operationId": "list_employees", "summary": "Beschäftigte", "description": "Alle Beschäftigten des Unternehmens, auch Stammsätze ohne Konto und Ausgetretene. Ohne Beispielpersonen und Verwaltungskonten. Recht: `employees:read`.", "tags": [ "Beschäftigte" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Nur dieser Status.", "schema": { "type": "string", "enum": [ "record_only", "invited", "active", "inactive", "left" ] } }, { "name": "unit_id", "in": "query", "required": false, "description": "Nur diese Einheit (Haupteinheit).", "schema": { "type": "string", "format": "uuid" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Nur, was seit diesem Zeitpunkt geändert wurde (ISO 8601 mit Zeitzone) — für den Abgleich.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "post_employees", "summary": "Beschäftigte anlegen (geplant)", "description": "Legt einen Stammsatz an. **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "employees:write" ] } ], "x-tiveo-planned": true, "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/employees/{id}": { "get": { "operationId": "get_employees", "summary": "Beschäftigte — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `employees:read`.", "tags": [ "Beschäftigte" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Employee" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "patch_employees_id", "summary": "Stammdaten ändern (geplant)", "description": "Ändert Name, Personalnummer, Einheit, Eintritt oder Austritt. **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "employees:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/units": { "get": { "operationId": "list_units", "summary": "Einheiten", "description": "Bereiche, Abteilungen, Teams und Standorte als Baum (`parent_id`), mit Leitung. Recht: `employees:read`.", "tags": [ "Einheiten" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Unit" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/units/{id}": { "get": { "operationId": "get_units", "summary": "Einheiten — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `employees:read`.", "tags": [ "Einheiten" ], "security": [ { "bearer": [ "employees:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Unit" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absence-types": { "get": { "operationId": "list_absence_types", "summary": "Abwesenheitsarten", "description": "Urlaub, Krankheit, Homeoffice und eigene Arten des Unternehmens. Recht: `absences:read`.", "tags": [ "Abwesenheitsarten" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AbsenceType" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absence-types/{id}": { "get": { "operationId": "get_absence_types", "summary": "Abwesenheitsarten — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `absences:read`.", "tags": [ "Abwesenheitsarten" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AbsenceType" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences": { "get": { "operationId": "list_absences", "summary": "Abwesenheiten", "description": "Anträge und eingetragene Abwesenheiten, ohne Entwürfe und ohne Freitext. Ohne absences:read_sensitive sind sensible Arten maskiert (`masked: true`, `type_id: null`). Recht: `absences:read`.", "tags": [ "Abwesenheiten" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Nur Abwesenheiten, die an diesem Tag oder später enden.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Nur Abwesenheiten, die an diesem Tag oder früher beginnen.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Nur dieser Status.", "schema": { "type": "string", "enum": [ "requested", "partially_approved", "approved", "rejected", "cancellation_requested", "cancelled" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "Nur, was seit diesem Zeitpunkt geändert wurde (ISO 8601 mit Zeitzone) — für den Abgleich.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Absence" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "post_absences", "summary": "Abwesenheit eintragen (geplant)", "description": "Trägt eine Abwesenheit ein oder stellt einen Antrag — mit den Regeln der App (Genehmigung, Sperren, Lizenz). **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}": { "get": { "operationId": "get_absences", "summary": "Abwesenheiten — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `absences:read`.", "tags": [ "Abwesenheiten" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Absence" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/leave-balances": { "get": { "operationId": "list_leave_balances", "summary": "Urlaubsstände", "description": "Je Person und Jahr Anspruch, genommen, beantragt, Rest und Übertrag — live gerechnet wie in der App. Geblättert wird nach Personen. Recht: `absences:read`.", "tags": [ "Urlaubsstände" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite (eine Personen-Kennung).", "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "required": false, "description": "Jahr, Vorgabe das laufende.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaveBalance" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/holidays": { "get": { "operationId": "list_holidays", "summary": "Feiertage und freie Tage", "description": "Gesetzliche Feiertage (nach Land und Region) und freie Tage des Betriebs eines Jahres, nach Datum. Ohne Blättern. Recht: `absences:read`.", "tags": [ "Feiertage und freie Tage" ], "security": [ { "bearer": [ "absences:read" ] } ], "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Jahr, Vorgabe das laufende.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "region", "in": "query", "required": false, "description": "Region wie NW oder BY, Vorgabe die Standardregion des Unternehmens.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Holiday" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/time-entries": { "get": { "operationId": "list_time_entries", "summary": "Stempelungen", "description": "Kommen, Gehen und Pausen, wie sie gelten: ohne aufgehobene und ersetzte Buchungen. Zeitraum höchstens 93 Tage. Recht: `time:read`. Nur wenn das Unternehmen das Modul Zeiterfassung nutzt.", "tags": [ "Stempelungen" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Erster Tag (JJJJ-MM-TT).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Letzter Tag, einschließlich.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntry" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "post_time_entries", "summary": "Arbeitszeit buchen (geplant)", "description": "Bucht Kommen, Gehen oder Pause. **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "time:write" ] } ], "x-tiveo-planned": true, "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/timesheets": { "get": { "operationId": "list_timesheets", "summary": "Tageswerte", "description": "Je Person und Tag Arbeit, Pause, Soll und Saldo in Minuten — gerechnet wie „Meine Zeiten“. Zeitraum höchstens 62 Tage; `limit` zählt Personen (Vorgabe 10, höchstens 25). Recht: `time:read`. Nur wenn das Unternehmen das Modul Zeiterfassung nutzt.", "tags": [ "Tageswerte" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Personen je Seite, Vorgabe 10.", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite (eine Personen-Kennung).", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Erster Tag; höchstens 62 Tage bis `to`.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Letzter Tag, einschließlich.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimesheetDay" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/projects": { "get": { "operationId": "list_projects", "summary": "Projekte", "description": "Projekte, auf die Beschäftigte Zeit buchen. Recht: `time:read`. Nur wenn das Unternehmen das Modul Zeiterfassung nutzt.", "tags": [ "Projekte" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/projects/{id}": { "get": { "operationId": "get_projects", "summary": "Projekte — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `time:read`. Nur wenn das Unternehmen das Modul Zeiterfassung nutzt.", "tags": [ "Projekte" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/project-times": { "get": { "operationId": "list_project_times", "summary": "Projektzeiten", "description": "Gebuchte Minuten je Person, Tag und Projekt. Zeitraum höchstens 93 Tage. Recht: `time:read`. Nur wenn das Unternehmen das Modul Zeiterfassung nutzt.", "tags": [ "Projektzeiten" ], "security": [ { "bearer": [ "time:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Erster Tag (JJJJ-MM-TT).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Letzter Tag, einschließlich.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "query", "required": false, "description": "Nur dieses Projekt.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTime" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/shift-types": { "get": { "operationId": "list_shift_types", "summary": "Schichtarten", "description": "Früh, Spät, Bereitschaft und weitere Arten mit Zeiten. Recht: `shifts:read`. Nur wenn das Unternehmen das Modul Schichtplanung nutzt.", "tags": [ "Schichtarten" ], "security": [ { "bearer": [ "shifts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShiftType" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/shift-types/{id}": { "get": { "operationId": "get_shift_types", "summary": "Schichtarten — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `shifts:read`. Nur wenn das Unternehmen das Modul Schichtplanung nutzt.", "tags": [ "Schichtarten" ], "security": [ { "bearer": [ "shifts:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ShiftType" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/shifts": { "get": { "operationId": "list_shifts", "summary": "Schichten", "description": "Veröffentlichte Schichten, auch ausgefallene und abgesagte; keine Entwürfe, keine Notizen. Zeitraum höchstens 93 Tage. Recht: `shifts:read`. Nur wenn das Unternehmen das Modul Schichtplanung nutzt.", "tags": [ "Schichten" ], "security": [ { "bearer": [ "shifts:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Erster Tag (JJJJ-MM-TT).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Letzter Tag, einschließlich.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } }, { "name": "unit_id", "in": "query", "required": false, "description": "Nur diese Einheit.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shift" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/vehicles": { "get": { "operationId": "list_vehicles", "summary": "Fahrzeuge", "description": "Firmenfahrzeuge (Pool und Dienstwagen) und eigene Autos von Beschäftigten für Kilometergeld, auch ausgemusterte. Recht: `vehicles:read`. Nur wenn das Unternehmen das Modul Fahrtenbuch nutzt.", "tags": [ "Fahrzeuge" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/vehicles/{id}": { "get": { "operationId": "get_vehicles", "summary": "Fahrzeuge — einzeln", "description": "Ein Eintrag nach Kennung. Recht: `vehicles:read`. Nur wenn das Unternehmen das Modul Fahrtenbuch nutzt.", "tags": [ "Fahrzeuge" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vehicle" } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Unbekannter Pfad oder unbekannte Kennung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/trips": { "get": { "operationId": "list_trips", "summary": "Fahrten", "description": "Fahrten in ihrer gültigen Fassung, ohne aufgehobene. Privatfahrt und Arbeitsweg nur mit Tag und Kilometern. Geschützte Geschäftspartner nur als Nummer. Nie die Route. Zeitraum höchstens 93 Tage. Recht: `vehicles:read`. Nur wenn das Unternehmen das Modul Fahrtenbuch nutzt.", "tags": [ "Fahrten" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Erster Tag (JJJJ-MM-TT).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Letzter Tag, einschließlich.", "schema": { "type": "string", "format": "date" } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } }, { "name": "vehicle_id", "in": "query", "required": false, "description": "Nur dieses Fahrzeug.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trip" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/vehicle-costs": { "get": { "operationId": "list_vehicle_costs", "summary": "Fahrzeugkosten", "description": "Kosten je Fahrzeug, ohne Notiz und ohne Beleg (nur ob es einen gibt). Zeitraum höchstens 366 Tage. Recht: `vehicles:read`. Nur wenn das Unternehmen das Modul Fahrtenbuch nutzt.", "tags": [ "Fahrzeugkosten" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": true, "description": "Erster Tag (JJJJ-MM-TT).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Letzter Tag, einschließlich.", "schema": { "type": "string", "format": "date" } }, { "name": "vehicle_id", "in": "query", "required": false, "description": "Nur dieses Fahrzeug.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleCost" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/mileage-allowances": { "get": { "operationId": "list_mileage_allowances", "summary": "Kilometergeld", "description": "Freigegebenes Kilometergeld für betriebliche Fahrten mit dem eigenen Auto: die jüngste Fassung je Person und Monat. Recht: `vehicles:read`. Nur wenn das Unternehmen das Modul Fahrtenbuch nutzt.", "tags": [ "Kilometergeld" ], "security": [ { "bearer": [ "vehicles:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, Vorgabe 50, höchstens die Seitengröße des Unternehmens (meist 200).", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` der vorigen Seite.", "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "required": false, "description": "Jahr, Vorgabe das laufende.", "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, { "name": "employee_id", "in": "query", "required": false, "description": "Nur diese Person.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Anfragen je Minute.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Übrig in dieser Minute.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Sekunden bis zur nächsten Minute.", "schema": { "type": "integer" } }, "X-Daily-Limit": { "description": "Anfragen je Tag.", "schema": { "type": "integer" } }, "X-Daily-Remaining": { "description": "Übrig heute.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MileageAllowance" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Kennung für die nächste Seite; null auf der letzten." } }, "required": [ "data", "next_cursor" ] } } } }, "400": { "description": "`invalid_parameter`: Ein Parameter fehlt oder stimmt nicht; `detail` nennt ihn.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`invalid_key`: Kein oder ein unbekannter API-Schlüssel. `key_revoked`: Der Schlüssel wurde widerrufen. `key_expired`: Der Schlüssel ist abgelaufen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Zu viele Anfragen je Minute; `Retry-After` sagt, wann es weitergeht. `daily_limit_reached`: Die Tagesgrenze des Unternehmens ist erreicht. `too_many_failed_attempts`: Zu viele ungültige Schlüssel von dieser Adresse; `Retry-After` sagt, wann es weitergeht (bis zu 15 Minuten).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`internal_error`: Fehler bei Tiveo; später erneut versuchen.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`server_busy`: Die API ist ausgelastet oder die Anfrage dauerte zu lang; `Retry-After` beachten, Zeitraum verkleinern.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}/approve": { "post": { "operationId": "post_absences_id_approve", "summary": "Antrag genehmigen (geplant)", "description": "Genehmigt einen offenen Antrag. **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}/reject": { "post": { "operationId": "post_absences_id_reject", "summary": "Antrag ablehnen (geplant)", "description": "Lehnt einen offenen Antrag ab. **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/absences/{id}/cancel": { "post": { "operationId": "post_absences_id_cancel", "summary": "Abwesenheit stornieren (geplant)", "description": "Storniert eine Abwesenheit. **Geplant — in der Beta antwortet dieser Weg immer mit 403 `write_not_available_in_beta`.**", "tags": [ "Schreiben (geplant)" ], "security": [ { "bearer": [ "absences:write" ] } ], "x-tiveo-planned": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "403": { "description": "`insufficient_scope`: Dem Schlüssel fehlt das nötige Recht. `plan_required`: Die API gibt es ab dem Paket Business. `api_paused`: Die API ist für dieses Unternehmen angehalten. `company_locked`: Das Konto des Unternehmens ist gesperrt oder beendet. `module_not_active`: Das Unternehmen nutzt das Modul nicht. `write_not_available_in_beta`: Schreiben steht in der Beta noch nicht zur Verfügung.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API-Schlüssel aus Einstellungen › Schnittstellen › API: `Authorization: Bearer tiveo_…`." } }, "schemas": { "Problem": { "type": "object", "description": "Fehler nach RFC 9457.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_key", "key_revoked", "key_expired", "insufficient_scope", "plan_required", "api_paused", "company_locked", "module_not_active", "write_not_available_in_beta", "not_found", "method_not_allowed", "rate_limited", "daily_limit_reached", "too_many_failed_attempts", "internal_error", "server_busy" ] }, "detail": { "type": "string" } }, "required": [ "type", "title", "status", "code" ] }, "Me": { "type": "object", "properties": { "beta": { "description": "Die API ist in der Beta.", "type": "boolean" }, "company": { "description": "Das Unternehmen des Schlüssels.", "type": "object", "properties": { "id": { "description": "Kennung des Unternehmens.", "type": "string", "format": "uuid" }, "name": { "description": "Name.", "type": "string" }, "country": { "description": "Land (DE, AT, CH).", "type": "string" }, "region": { "description": "Standardregion für Feiertage.", "type": [ "string", "null" ] }, "time_zone": { "description": "Zeitzone.", "type": "string" } }, "required": [ "id", "name", "country", "region", "time_zone" ] }, "key": { "description": "Der Schlüssel.", "type": "object", "properties": { "id": { "description": "Kennung des Schlüssels.", "type": "string", "format": "uuid" }, "name": { "description": "Name, den das Unternehmen vergeben hat.", "type": "string" }, "scopes": { "description": "Rechte.", "type": "array", "items": { "type": "string" } }, "expires_on": { "description": "Läuft ab (einschließlich dieses Tages gültig).", "type": [ "string", "null" ], "format": "date" } }, "required": [ "id", "name", "scopes", "expires_on" ] }, "limits": { "description": "Grenzen des Unternehmens.", "type": "object", "properties": { "per_minute": { "description": "Anfragen je Minute.", "type": "integer" }, "per_day": { "description": "Anfragen je Tag.", "type": "integer" }, "max_page_size": { "description": "Größte Seite (`limit`).", "type": "integer" } }, "required": [ "per_minute", "per_day", "max_page_size" ] }, "modules": { "description": "Welche Module das Unternehmen nutzt.", "type": "object", "properties": { "time_tracking": { "description": "Zeiterfassung.", "type": "boolean" }, "shift_planning": { "description": "Schichtplanung.", "type": "boolean" }, "vehicle_logbook": { "description": "Fahrtenbuch.", "type": "boolean" } }, "required": [ "time_tracking", "shift_planning", "vehicle_logbook" ] }, "write_access": { "description": "Schreiben möglich — in der Beta immer false.", "type": "boolean" } }, "required": [ "beta", "company", "key", "limits", "modules", "write_access" ], "example": { "beta": true, "company": { "id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "name": "Tischlerei Muster GmbH", "country": "DE", "region": "NW", "time_zone": "Europe/Berlin" }, "key": { "id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "name": "Lohnbüro", "scopes": [ "employees:read", "absences:read" ], "expires_on": null }, "limits": { "per_minute": 60, "per_day": 10000, "max_page_size": 200 }, "modules": { "time_tracking": true, "shift_planning": false, "vehicle_logbook": false }, "write_access": false } }, "Employee": { "type": "object", "properties": { "id": { "description": "Kennung der Person in diesem Unternehmen.", "type": "string", "format": "uuid" }, "personnel_number": { "description": "Personalnummer.", "type": [ "string", "null" ] }, "display_name": { "description": "Angezeigter Name.", "type": "string" }, "first_name": { "description": "Vorname (aus dem Konto, sonst leer).", "type": [ "string", "null" ] }, "last_name": { "description": "Nachname (aus dem Konto, sonst leer).", "type": [ "string", "null" ] }, "email": { "description": "E-Mail-Adresse.", "type": [ "string", "null" ] }, "role": { "description": "Rolle in Tiveo.", "type": "string", "enum": [ "owner", "admin", "hr", "manager", "employee" ] }, "status": { "description": "record_only = Stammsatz ohne Konto, invited = eingeladen, active, inactive = ruht, left = ausgetreten.", "type": "string", "enum": [ "record_only", "invited", "active", "inactive", "left" ] }, "unit_id": { "description": "Haupteinheit.", "type": [ "string", "null" ], "format": "uuid" }, "additional_unit_ids": { "description": "Weitere Einheiten.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "region": { "description": "Region für Feiertage, wenn abweichend.", "type": [ "string", "null" ] }, "entry_date": { "description": "Eintritt.", "type": [ "string", "null" ], "format": "date" }, "exit_date": { "description": "Austritt.", "type": [ "string", "null" ], "format": "date" }, "weekly_hours": { "description": "Wochenstunden laut heutigem Arbeitsmodell.", "type": [ "number", "null" ] }, "created_at": { "description": "Angelegt.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "personnel_number", "display_name", "first_name", "last_name", "email", "role", "status", "unit_id", "additional_unit_ids", "region", "entry_date", "exit_date", "weekly_hours", "created_at", "updated_at" ], "example": { "id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "personnel_number": "00042", "display_name": "Anna Achter", "first_name": "Anna", "last_name": "Achter", "email": "anna.achter@example.com", "role": "employee", "status": "active", "unit_id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "additional_unit_ids": [], "region": null, "entry_date": "2024-01-01", "exit_date": null, "weekly_hours": 40, "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "Unit": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "parent_id": { "description": "Übergeordnete Einheit.", "type": [ "string", "null" ], "format": "uuid" }, "name": { "description": "Name.", "type": "string" }, "type": { "description": "Art.", "type": "string", "enum": [ "division", "department", "team", "location" ] }, "region": { "description": "Region für Feiertage.", "type": [ "string", "null" ] }, "active": { "description": "Aktiv.", "type": "boolean" }, "sort_order": { "description": "Reihenfolge.", "type": [ "integer", "null" ] }, "leads": { "description": "Leitung und Stellvertretung.", "type": "array", "items": { "type": "object", "properties": { "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "kind": { "description": "Leitung oder Stellvertretung.", "type": "string", "enum": [ "lead", "deputy" ] } }, "required": [ "employee_id", "kind" ] } }, "created_at": { "description": "Angelegt.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "parent_id", "name", "type", "region", "active", "sort_order", "leads", "created_at", "updated_at" ], "example": { "id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "parent_id": null, "name": "Werkstatt", "type": "team", "region": null, "active": true, "sort_order": 10, "leads": [ { "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "kind": "lead" } ], "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "AbsenceType": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "key": { "description": "Schlüssel (urlaub, krankheit … oder eigener).", "type": "string" }, "name": { "description": "Name auf Deutsch und Englisch.", "type": "object", "properties": { "de": { "description": "Deutsch.", "type": "string" }, "en": { "description": "Englisch.", "type": "string" } }, "required": [ "de", "en" ] }, "short_name": { "description": "Kürzel (1–3 Zeichen).", "type": "string" }, "color": { "description": "Farbe (#rrggbb).", "type": "string" }, "text_color": { "description": "Schriftfarbe (#rrggbb).", "type": "string" }, "counts_against_allowance": { "description": "Zählt auf den Urlaubsanspruch.", "type": "boolean" }, "requires_approval": { "description": "Braucht eine Genehmigung.", "type": "boolean" }, "requires_certificate": { "description": "Braucht einen Nachweis.", "type": "boolean" }, "half_days_allowed": { "description": "Halbe Tage erlaubt.", "type": "boolean" }, "sensitive": { "description": "Sensibel (z. B. Krankheit): ohne absences:read_sensitive maskiert.", "type": "boolean" }, "active": { "description": "Aktiv.", "type": "boolean" }, "sort_order": { "description": "Reihenfolge.", "type": [ "integer", "null" ] } }, "required": [ "id", "key", "name", "short_name", "color", "text_color", "counts_against_allowance", "requires_approval", "requires_certificate", "half_days_allowed", "sensitive", "active", "sort_order" ], "example": { "id": "b7d1e2f3-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "key": "urlaub", "name": { "de": "Urlaub", "en": "Annual leave" }, "short_name": "U", "color": "#1a7d57", "text_color": "#ffffff", "counts_against_allowance": true, "requires_approval": true, "requires_certificate": false, "half_days_allowed": true, "sensitive": false, "active": true, "sort_order": 10 } }, "Absence": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "type_id": { "description": "Abwesenheitsart; null, wenn maskiert.", "type": [ "string", "null" ], "format": "uuid" }, "masked": { "description": "Art verborgen (sensibel, Recht fehlt).", "type": "boolean" }, "start_date": { "description": "Erster Tag.", "type": "string", "format": "date" }, "end_date": { "description": "Letzter Tag.", "type": "string", "format": "date" }, "start_day_part": { "description": "Erster Tag ganz oder halb.", "type": "string", "enum": [ "full", "morning", "afternoon" ] }, "end_day_part": { "description": "Letzter Tag ganz oder halb.", "type": "string", "enum": [ "full", "morning", "afternoon" ] }, "working_days": { "description": "Arbeitstage, die die Abwesenheit kostet.", "type": "number" }, "status": { "description": "Stand des Antrags.", "type": "string", "enum": [ "requested", "partially_approved", "approved", "rejected", "cancellation_requested", "cancelled" ] }, "created_at": { "description": "Angelegt.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "type_id", "masked", "start_date", "end_date", "start_day_part", "end_day_part", "working_days", "status", "created_at", "updated_at" ], "example": { "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "type_id": "b7d1e2f3-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "masked": false, "start_date": "2026-08-03", "end_date": "2026-08-14", "start_day_part": "full", "end_day_part": "full", "working_days": 10, "status": "approved", "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "LeaveBalance": { "type": "object", "properties": { "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "year": { "description": "Jahr.", "type": "integer" }, "entitlement": { "description": "Anspruch in Tagen (mit Übertrag).", "type": [ "number", "null" ] }, "approved": { "description": "Genehmigt.", "type": [ "number", "null" ] }, "requested": { "description": "Beantragt, noch offen.", "type": [ "number", "null" ] }, "remaining": { "description": "Rest.", "type": [ "number", "null" ] }, "carry_over": { "description": "Übertrag aus dem Vorjahr.", "type": [ "number", "null" ] }, "carry_over_remaining": { "description": "Davon noch offen.", "type": [ "number", "null" ] }, "carry_over_expires_on": { "description": "Übertrag verfällt am.", "type": [ "string", "null" ], "format": "date" }, "expiring": { "description": "Verfällt bald.", "type": [ "number", "null" ] }, "expired": { "description": "Verfallen.", "type": [ "number", "null" ] }, "paid_out": { "description": "Ausgezahlt.", "type": [ "number", "null" ] } }, "required": [ "employee_id", "year", "entitlement", "approved", "requested", "remaining", "carry_over", "carry_over_remaining", "carry_over_expires_on", "expiring", "expired", "paid_out" ], "example": { "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "year": 2026, "entitlement": 30, "approved": 18, "requested": 2, "remaining": 10, "carry_over": 3, "carry_over_remaining": 0, "carry_over_expires_on": "2026-03-31", "expiring": 0, "expired": 0, "paid_out": 0 } }, "Holiday": { "type": "object", "properties": { "date": { "description": "Tag.", "type": "string", "format": "date" }, "name": { "description": "Name.", "type": "string" }, "kind": { "description": "Gesetzlich oder vom Betrieb.", "type": "string", "enum": [ "public_holiday", "company_day_off" ] }, "region": { "description": "Region.", "type": [ "string", "null" ] }, "unit_id": { "description": "Nur für diese Einheit (freie Tage).", "type": [ "string", "null" ], "format": "uuid" }, "value": { "description": "1 ganzer, 0.5 halber Tag.", "type": "number" }, "deducted_from_leave": { "description": "Zählt auf den Urlaub.", "type": "boolean" } }, "required": [ "date", "name", "kind", "region", "unit_id", "value", "deducted_from_leave" ], "example": { "date": "2026-12-25", "name": "1. Weihnachtstag", "kind": "public_holiday", "region": "NW", "unit_id": null, "value": 1, "deducted_from_leave": false } }, "TimeEntry": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "kind": { "description": "Art.", "type": "string", "enum": [ "clock_in", "clock_out", "break_start", "break_end" ] }, "timestamp": { "description": "Zeitpunkt.", "type": "string", "format": "date-time" }, "work_date": { "description": "Arbeitstag, dem die Buchung gehört.", "type": "string", "format": "date" }, "source": { "description": "Herkunft.", "type": "string", "enum": [ "app", "terminal", "manual", "correction", "import", "automatic", "sample" ] }, "location": { "description": "Ort.", "type": [ "string", "null" ], "enum": [ "on_site", "remote", null ] }, "recorded_at": { "description": "Erfasst am.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "kind", "timestamp", "work_date", "source", "location", "recorded_at" ], "example": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "kind": "clock_in", "timestamp": "2026-10-19T06:58:00Z", "work_date": "2026-10-19", "source": "app", "location": "on_site", "recorded_at": "2026-10-19T06:58:02Z" } }, "TimesheetDay": { "type": "object", "properties": { "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "date": { "description": "Tag.", "type": "string", "format": "date" }, "recorded": { "description": "Es gibt Buchungen.", "type": "boolean" }, "start": { "description": "Beginn.", "type": [ "string", "null" ], "format": "date-time" }, "end": { "description": "Ende.", "type": [ "string", "null" ], "format": "date-time" }, "work_minutes": { "description": "Arbeit.", "type": [ "integer", "null" ] }, "break_minutes": { "description": "Pause.", "type": [ "integer", "null" ] }, "deducted_break_minutes": { "description": "Pause, die nach der Pausenregel abgezogen wurde.", "type": [ "integer", "null" ] }, "target_minutes": { "description": "Soll.", "type": [ "integer", "null" ] }, "credit_minutes": { "description": "Gutschrift (Urlaub, Krankheit, Feiertag).", "type": [ "integer", "null" ] }, "balance_minutes": { "description": "Saldo des Tages. Leer, wenn der Tag noch läuft oder der Betrieb offene Tage getrennt führt und das Gehen fehlt (`open`).", "type": [ "integer", "null" ] }, "open": { "description": "Unvollständig (z. B. Gehen fehlt).", "type": [ "boolean", "null" ] }, "running": { "description": "Läuft gerade.", "type": [ "boolean", "null" ] }, "violations": { "description": "Hinweise nach Arbeitszeitgesetz (Kürzel).", "type": "array", "items": { "type": "string" } }, "absent": { "description": "An dem Tag abwesend (ohne Art).", "type": "boolean" } }, "required": [ "employee_id", "date", "recorded", "start", "end", "work_minutes", "break_minutes", "deducted_break_minutes", "target_minutes", "credit_minutes", "balance_minutes", "open", "running", "violations", "absent" ], "example": { "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "date": "2026-10-19", "recorded": true, "start": "2026-10-19T06:58:00Z", "end": "2026-10-19T15:31:00Z", "work_minutes": 483, "break_minutes": 30, "deducted_break_minutes": 0, "target_minutes": 480, "credit_minutes": 0, "balance_minutes": 3, "open": false, "running": false, "violations": [], "absent": false } }, "Project": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "number": { "description": "Projektnummer.", "type": [ "string", "null" ] }, "title": { "description": "Titel.", "type": "string" }, "link": { "description": "Verweis.", "type": [ "string", "null" ] }, "contact_employee_id": { "description": "Ansprechperson.", "type": [ "string", "null" ], "format": "uuid" }, "active": { "description": "Aktiv.", "type": "boolean" }, "created_at": { "description": "Angelegt.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "number", "title", "link", "contact_employee_id", "active", "created_at", "updated_at" ], "example": { "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "number": "P-2026-014", "title": "Dachstuhl Hauptstraße", "link": null, "contact_employee_id": null, "active": true, "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "ProjectTime": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "date": { "description": "Tag.", "type": "string", "format": "date" }, "project_id": { "description": "Projekt; leer bei freiem Text.", "type": [ "string", "null" ], "format": "uuid" }, "text": { "description": "Freier Text statt Projekt.", "type": [ "string", "null" ] }, "minutes": { "description": "Minuten.", "type": "integer" }, "note": { "description": "Notiz.", "type": [ "string", "null" ] }, "recorded_at": { "description": "Erfasst am.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "date", "project_id", "text", "minutes", "note", "recorded_at", "updated_at" ], "example": { "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "date": "2026-10-19", "project_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "text": null, "minutes": 240, "note": null, "recorded_at": "2026-10-19T15:40:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "ShiftType": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "unit_id": { "description": "Einheit.", "type": [ "string", "null" ], "format": "uuid" }, "name": { "description": "Name.", "type": "string" }, "short_name": { "description": "Kürzel.", "type": "string" }, "color": { "description": "Farbe (#rrggbb).", "type": "string" }, "start_time": { "description": "Beginn (Ortszeit).", "type": [ "string", "null" ], "format": "time" }, "end_time": { "description": "Ende (Ortszeit).", "type": [ "string", "null" ], "format": "time" }, "break_minutes": { "description": "Pause.", "type": "integer" }, "kind": { "description": "Art.", "type": "string", "enum": [ "shift", "on_call_duty", "standby", "training", "appointment" ] }, "active": { "description": "Aktiv.", "type": "boolean" }, "sort_order": { "description": "Reihenfolge.", "type": [ "integer", "null" ] } }, "required": [ "id", "unit_id", "name", "short_name", "color", "start_time", "end_time", "break_minutes", "kind", "active", "sort_order" ], "example": { "id": "f7a8b9c0-d1e2-4f3a-9b4c-5d6e7f8a9b0c", "unit_id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "name": "Frühdienst", "short_name": "F", "color": "#2563eb", "start_time": "06:00:00", "end_time": "14:00:00", "break_minutes": 30, "kind": "shift", "active": true, "sort_order": 10 } }, "Shift": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Person; leer bei offener Schicht.", "type": [ "string", "null" ], "format": "uuid" }, "unit_id": { "description": "Einheit.", "type": "string", "format": "uuid" }, "shift_type_id": { "description": "Schichtart.", "type": [ "string", "null" ], "format": "uuid" }, "date": { "description": "Tag.", "type": "string", "format": "date" }, "start": { "description": "Beginn.", "type": "string", "format": "date-time" }, "end": { "description": "Ende.", "type": "string", "format": "date-time" }, "break_minutes": { "description": "Pause.", "type": "integer" }, "status": { "description": "Stand.", "type": "string", "enum": [ "published", "dropped", "cancelled" ] }, "dropped_reason": { "description": "Grund eines Ausfalls; „sickness“ nur mit absences:read_sensitive, sonst „absence“.", "type": [ "string", "null" ], "enum": [ "leave", "sickness", "absence", "company", null ] }, "published_at": { "description": "Veröffentlicht am.", "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "unit_id", "shift_type_id", "date", "start", "end", "break_minutes", "status", "dropped_reason", "published_at", "updated_at" ], "example": { "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "unit_id": "8c0e4f7a-2d1b-4c3e-9a55-6f7e8d9c0b1a", "shift_type_id": "f7a8b9c0-d1e2-4f3a-9b4c-5d6e7f8a9b0c", "date": "2026-10-20", "start": "2026-10-20T04:00:00Z", "end": "2026-10-20T12:00:00Z", "break_minutes": 30, "status": "published", "dropped_reason": null, "published_at": "2026-10-01T09:00:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "Vehicle": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "license_plate": { "description": "Kennzeichen.", "type": "string" }, "name": { "description": "Bezeichnung.", "type": [ "string", "null" ] }, "kind": { "description": "Firmenfahrzeug oder eigenes Auto einer beschäftigten Person.", "type": "string", "enum": [ "company", "private" ] }, "usage": { "description": "Poolfahrzeug oder Dienstwagen; leer beim eigenen Auto.", "type": [ "string", "null" ], "enum": [ "pool", "assigned", null ] }, "private_use": { "description": "Privatfahrten erlaubt.", "type": "boolean" }, "drive": { "description": "Antrieb.", "type": "string", "enum": [ "combustion", "hybrid", "electric" ] }, "list_price": { "description": "Bruttolistenpreis in Euro.", "type": [ "number", "null" ] }, "first_registration": { "description": "Erstzulassung.", "type": [ "string", "null" ], "format": "date" }, "start_odometer": { "description": "Kilometerstand zu Beginn des Fahrtenbuchs.", "type": "integer" }, "logbook_from": { "description": "Fahrtenbuch ab.", "type": "string", "format": "date" }, "inspection_due": { "description": "Hauptuntersuchung fällig.", "type": [ "string", "null" ], "format": "date" }, "safety_check_due": { "description": "UVV-Prüfung fällig.", "type": [ "string", "null" ], "format": "date" }, "owner_employee_id": { "description": "Halterin oder Halter beim eigenen Auto.", "type": [ "string", "null" ], "format": "uuid" }, "unit_id": { "description": "Standort.", "type": [ "string", "null" ], "format": "uuid" }, "retired_on": { "description": "Ausgemustert ab.", "type": [ "string", "null" ], "format": "date" }, "created_at": { "description": "Angelegt.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "license_plate", "name", "kind", "usage", "private_use", "drive", "list_price", "first_registration", "start_odometer", "logbook_from", "inspection_due", "safety_check_due", "owner_employee_id", "unit_id", "retired_on", "created_at", "updated_at" ], "example": { "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "license_plate": "D-AB 123", "name": "Caddy", "kind": "company", "usage": "pool", "private_use": false, "drive": "combustion", "list_price": 38500, "first_registration": "2024-03-01", "start_odometer": 12500, "logbook_from": "2026-11-01", "inspection_due": "2027-05-31", "safety_check_due": null, "owner_employee_id": null, "unit_id": null, "retired_on": null, "created_at": "2026-03-02T08:14:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "Trip": { "type": "object", "properties": { "id": { "description": "Kennung der Fahrt (gleich über alle Fassungen).", "type": "string", "format": "uuid" }, "version": { "description": "Fassung; jede Änderung ist eine neue.", "type": "integer" }, "journey_id": { "description": "Reise: Teile einer Mischfahrt haben dieselbe.", "type": "string", "format": "uuid" }, "split_from_id": { "description": "Abgeteilt aus dieser Fahrt.", "type": [ "string", "null" ], "format": "uuid" }, "vehicle_id": { "description": "Fahrzeug.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Fahrende Person.", "type": "string", "format": "uuid" }, "category": { "description": "Betrieblich, privat oder Arbeitsweg.", "type": "string", "enum": [ "business", "private", "commute" ] }, "date": { "description": "Tag (Ortszeit).", "type": "string", "format": "date" }, "start": { "description": "Beginn; leer bei Privatfahrt und Arbeitsweg.", "type": [ "string", "null" ], "format": "date-time" }, "end": { "description": "Ende; leer, solange sie läuft, und bei Privatfahrt und Arbeitsweg.", "type": [ "string", "null" ], "format": "date-time" }, "odometer_start": { "description": "Kilometerstand am Beginn.", "type": [ "integer", "null" ] }, "odometer_end": { "description": "Kilometerstand am Ende.", "type": [ "integer", "null" ] }, "distance_km": { "description": "Gefahrene Kilometer.", "type": [ "integer", "null" ] }, "origin": { "description": "Start; geschützte Partner als „Nr. 17“.", "type": [ "string", "null" ] }, "destination": { "description": "Reiseziel; geschützte Partner als „Nr. 17“.", "type": [ "string", "null" ] }, "purpose": { "description": "Reisezweck.", "type": [ "string", "null" ] }, "business_partner": { "description": "Aufgesuchter Geschäftspartner; geschützte Partner als „Nr. 17“.", "type": [ "string", "null" ] }, "detour": { "description": "Umweg und Grund.", "type": [ "string", "null" ] }, "project_id": { "description": "Projekt.", "type": [ "string", "null" ], "format": "uuid" }, "status": { "description": "Läuft, offen (kann noch ergänzt werden) oder abgeschlossen.", "type": "string", "enum": [ "running", "open", "closed" ] }, "incomplete": { "description": "Es fehlen Angaben.", "type": "boolean" }, "changed": { "description": "Nach der Erfassung geändert (Verlauf in Tiveo).", "type": "boolean" }, "late_entry": { "description": "Nachgetragen oder nach der Frist erfasst.", "type": "boolean" }, "recorded_at": { "description": "Erfasst am (erste Fassung); leer bei Privatfahrt und Arbeitsweg.", "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "description": "Diese Fassung erfasst am; leer bei Privatfahrt und Arbeitsweg.", "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "version", "journey_id", "split_from_id", "vehicle_id", "employee_id", "category", "date", "start", "end", "odometer_start", "odometer_end", "distance_km", "origin", "destination", "purpose", "business_partner", "detour", "project_id", "status", "incomplete", "changed", "late_entry", "recorded_at", "updated_at" ], "example": { "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "version": 2, "journey_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f", "split_from_id": null, "vehicle_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "category": "business", "date": "2026-11-03", "start": "2026-11-03T07:40:00Z", "end": "2026-11-03T08:25:00Z", "odometer_start": 12500, "odometer_end": 12542, "distance_km": 42, "origin": "Werkstatt", "destination": "Kunde Meier, Hauptstraße 1, 40210 Düsseldorf", "purpose": "Wartung Heizung", "business_partner": "Herr Meier", "detour": null, "project_id": null, "status": "closed", "incomplete": false, "changed": false, "late_entry": false, "recorded_at": "2026-11-03T07:40:05Z", "updated_at": "2026-11-03T08:26:10Z" } }, "VehicleCost": { "type": "object", "properties": { "id": { "description": "Kennung.", "type": "string", "format": "uuid" }, "vehicle_id": { "description": "Fahrzeug.", "type": "string", "format": "uuid" }, "date": { "description": "Tag.", "type": "string", "format": "date" }, "kind": { "description": "Art.", "type": "string", "enum": [ "fuel", "charging", "workshop", "tyres", "insurance", "tax", "leasing", "financing", "depreciation", "tolls_parking", "cleaning", "other" ] }, "amount_gross": { "description": "Betrag brutto in Euro.", "type": "number" }, "amount_net": { "description": "Betrag netto in Euro.", "type": [ "number", "null" ] }, "quantity": { "description": "Menge (Liter oder kWh).", "type": [ "number", "null" ] }, "odometer": { "description": "Kilometerstand.", "type": [ "integer", "null" ] }, "has_receipt": { "description": "Ein Beleg liegt in Tiveo.", "type": "boolean" }, "recorded_at": { "description": "Erfasst am.", "type": "string", "format": "date-time" }, "updated_at": { "description": "Zuletzt geändert.", "type": "string", "format": "date-time" } }, "required": [ "id", "vehicle_id", "date", "kind", "amount_gross", "amount_net", "quantity", "odometer", "has_receipt", "recorded_at", "updated_at" ], "example": { "id": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a", "vehicle_id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e", "date": "2026-11-04", "kind": "fuel", "amount_gross": 71.4, "amount_net": 60, "quantity": 38.2, "odometer": 12542, "has_receipt": true, "recorded_at": "2026-11-04T16:02:00Z", "updated_at": "2026-10-01T12:30:00Z" } }, "MileageAllowance": { "type": "object", "properties": { "id": { "description": "Kennung dieser Freigabe.", "type": "string", "format": "uuid" }, "employee_id": { "description": "Person.", "type": "string", "format": "uuid" }, "month": { "description": "Monat (der Erste).", "type": "string", "format": "date" }, "version": { "description": "Fassung; eine neue Freigabe ersetzt die alte.", "type": "integer" }, "distance_km": { "description": "Kilometer.", "type": "integer" }, "rate": { "description": "Satz je Kilometer in Euro.", "type": "number" }, "amount": { "description": "Betrag in Euro.", "type": "number" }, "trip_count": { "description": "Fahrten.", "type": "integer" }, "approved_at": { "description": "Freigegeben am.", "type": "string", "format": "date-time" } }, "required": [ "id", "employee_id", "month", "version", "distance_km", "rate", "amount", "trip_count", "approved_at" ], "example": { "id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b", "employee_id": "3f2a9c1e-7b4d-4e8a-9f61-2c5d8e0b1a74", "month": "2026-10-01", "version": 1, "distance_km": 420, "rate": 0.3, "amount": 126, "trip_count": 18, "approved_at": "2026-11-02T09:15:00Z" } } } } }