Zum Hauptinhalt springen

Beta-Status und Changelog

Beta Aktuelle Version: 1.0.0-beta.1

Was die Beta bedeutet​

Die TimeMonkey REST-API ist in der Beta. Bis zur Version 1.0.0 können sich Endpunkte und Felder noch ändern. Für deine Anbindung heißt das:

  • Prüfe vor dem Einsatz, ob die Daten für deinen Zweck passen, und plane Zeit für Anpassungen ein.
  • Werte Fehler über den Fehlercode code aus, nicht über den Meldungstext (siehe Fehler und Rate-Limits).
  • Behalte dieses Changelog und die Version in der OpenAPI-Spezifikation im Blick.

Versionierung​

Die Versionsnummern folgen der semantischen Versionierung (SemVer). Die Version der Schnittstelle steht im Pfad: alle Endpunkte liegen unter /api/v1. Brechende Änderungen sind nur mit einer neuen Pfad-Version wie /api/v2 vorgesehen. Während der Beta gilt zusätzlich: Bis 1.0.0 können sich Endpunkte und Felder noch ändern.

Feedback zur Beta​

Rückmeldungen helfen uns, die API weiterzuentwickeln. Schreib dem Support, was gut funktioniert, was dir fehlt oder was dich stört – in der Webapp über Support unten in der linken Menüleiste und dann Support-Anfrage erstellen. Hilfreich sind:

  • welches System du anbindest und welche Daten du dafür brauchst,
  • der betroffene Endpunkt mit seinen Parametern,
  • bei Fehlern der Fehlercode und die X-Request-Id aus dem Antwort-Header.

Sende dabei niemals deinen API-Key mit.

Changelog​

1.0.0-beta.1​

Erste Version der REST-API, nur lesend und als Beta.

Endpunkte

  • GET /api/v1/company – Standort mit aktueller Adresse und Zeitzone
  • GET /api/v1/employees und GET /api/v1/employees/{id} – Mitarbeiter mit aktuellen Vertragswerten, optional mit include=contractHistory
  • GET /api/v1/stamps – sichtbare Stempel mit grober Herkunft sourceType
  • GET /api/v1/absences – Abwesenheiten mit Antragsstatus und halben Tagen
  • GET /api/v1/shifts und GET /api/v1/areas – veröffentlichte Schichten und Arbeitsbereiche
  • GET /api/v1/evaluations/days – Tagesauswertung je Mitarbeiter
  • GET /api/v1/openapi.json – Spezifikation im Format OpenAPI 3.0.3, ohne API-Key abrufbar

Zugang und Limits

  • Scopes employees:read, stamps:read, absences:read, shifts:read und evaluations:read
  • Limits pro API-Key: 60 Requests pro Minute und 1.000 pro Tag
  • Fehlercodes payment_locked (offene Zahlung nach Fristende) und company_pending_review (Standort in Prüfung), beide mit HTTP-Status 403
  • Einheitliche JSON-Fehler mit method_not_allowed und Header Allow: GET für andere Methoden als GET

Salden und Urlaubskonto (ergänzt am 8. November 2026)

  • GET /api/v1/evaluations/months – neu: Monatssaldo und Arbeitszeitkonto je Mitarbeiter und Monat
  • GET /api/v1/evaluations/years – neu: Stundenübertrag, Jahressaldo, Arbeitszeitkonto und Urlaubskonto je Mitarbeiter
  • GET /api/v1/evaluations/days rechnet jetzt wie die Monatsauswertung in TimeMonkey und liefert zusätzlich contractMs, creditMs, compensatedOvertimeMs, balanceMs, dailyDeductionMs, holiday, absences und accountPaused. Zeilen gibt es jetzt auch für Tage mit Soll oder Abwesenheit ohne Stempel und Schicht.
  • Geänderte Werte bisheriger Felder von GET /api/v1/evaluations/days nur dort, wo TimeMonkey so rechnet: vor Vertragsbeginn, nach dem Austritt und bei Elternzeit mit pausiertem Arbeitszeitkonto sind workedMs, plannedMs und legalBreakMs jetzt 0; an Feiertagen richtet sich workedMs nach der Feiertagseinstellung.
  • Die Auswertungs-Endpunkte begrenzen die Rechenzeit pro Seite. Eine Seite kann deshalb weniger Einträge als limit enthalten; maßgeblich ist nextCursor.
  • Hinweise zur fairen Nutzung ergänzt
  • Die Berechtigung für evaluations:read heißt in TimeMonkey jetzt Auswertungen statt „Tagesauswertungen“. Scope und bestehende Keys bleiben unverändert.