REST-API für Zeiterfassung

Externe Zeiterfassungs-Tools (z. B. Desktop-Timer, Tracker-Apps, Skripte) verbinden sich über die REST-API. Jede Person legt dafür unter Einstellungen → API-Tokens eigene Tokens an; die API arbeitet immer im Namen dieser Person und mit deren Projektsichtbarkeit.

Token anlegen

1. Einstellungen → API-Tokens, Name vergeben (z. B. „Toggl-Sync“).
2. Berechtigungen wählen: time:read (Zeiten lesen) und/oder time:write (Zeiten schreiben, Timer steuern).
3. Token anlegen. Der Token wird nur einmal angezeigt – sofort kopieren.

Tokens lassen sich jederzeit widerrufen; verbundene Tools verlieren dann sofort den Zugriff. Anlegen und Widerruf stehen im Audit-Log.

Endpunkte

Basis-URL: https://<ihre-domain>/api/v1, Header Authorization: Bearer <token> und Accept: application/json. Limit: 120 Anfragen pro Minute.

Methode	Pfad	Berechtigung	Zweck
GET	/me	–	Eigenes Profil, Sprache, Token-Berechtigungen
GET	/projects	–	Offene Projekte mit Kunde und Aufgaben (nur sichtbare)
GET	/time-entries?from=&to=&project_id=&per_page=	time:read	Eigene Buchungen, paginiert
POST	/time-entries	time:write	Buchung anlegen
PATCH	/time-entries/{id}	time:write	Buchung ändern (nur Entwurf/abgelehnt)
DELETE	/time-entries/{id}	time:write	Buchung löschen (nur Entwurf/abgelehnt)
POST	/timer/start	time:write	Timer starten (laufender Timer wird gestoppt)
POST	/timer/stop	time:write	Timer stoppen

Buchung anlegen

POST /api/v1/time-entries
{
  "project_id": 12,
  "task_id": 40,
  "activity_type_id": 2,
  "date": "2026-09-24",
  "minutes": 90,
  "description": "Konzept überarbeitet",
  "billable": true,
  "external_id": "toggl-8812"
}

Statt minutes kann hours (Dezimal) übergeben werden. Die Antwort enthält die Buchung im selben Format wie die Webhooks; Stundensätze erscheinen nur, wenn die Person das Recht Stundensätze sehen hat.

Regeln

• Eingereichte, freigegebene oder abgerechnete Buchungen sind über die API gesperrt (HTTP 409).
• Fremde Buchungen sind nicht änderbar (HTTP 403); Projekte außerhalb der eigenen Sichtbarkeit liefern HTTP 403.
• Jede API-Änderung löst dieselben Webhook-Ereignisse aus wie die Oberfläche.