« Zurück zur Übersicht
API zur Online Zeiterfassung: REST-Schnittstelle

API zur Online Zeiterfassung: REST-Schnittstelle v2.1

Hier finden Sie die Dokumentation für die alte Version REST-API v1.1.

Technische Beschreibung für Softwareentwickler

Die Zeiterfassung bietet eine REST-Schnittstelle für Softwareentwickler. Dieser REST-Service ist zum Beispiel auch geeignet für die Anbindung von Stempeluhren.

Voraussetzungen

Das REST-API muss in den Einstellungen der Zeiterfassung (Reiter Sicherheit) aktiviert und ein Passwort gesetzt werden.

Wechsel von Version v1.1 zu Version v2.1

Bitte beachten Sie beim Upgrade von der Version 1.1 folgende Änderungen:

  • Alle Ressourcen mit Pfaden mit ../time/.. sind in Version 2.1 erreichbar unter in ../time-v2.1/..
  • Der Endpoint @GET /api/time/timecategories wurde umbenannt in @GET /api/time-v2.1/timetypes
  • Die Ressource @POST /api/time-v2.1/createtimeentry hat einen neuen, optionalen Parameter: comment

Testmöglichkeiten

Eine Hello-World-Ressource ist erreichbar unter:

Eine Test-Ressource für das Login ist erreichbar unter:

Einfache Demo Clients für alle verfügbaren REST-API-Funktionen:

Beschreibung der Ressourcen

Ressource @GET /api/hello/sayhello

Diese Ressource zum Testen gibt ein Hallo zurück.

Parameter:
Keine
Rückgabewert:
String
'Hello!'

Ressource @GET /api/hello/securedSayhello

Diese Ressource kann zum Testen des Logins verwendet werden. Das Login muss zuvor aufgerufen werden.

Parameter:
Keine
Rückgabewert:
String
'Secured Hello!'

Ressource @POST /api/login

Diese Ressource kann für das Login verwendet werden.

Parameter:
{loginemail, apipassword}
Als loginemail wird die Loginemail des Admins verwendet. Das API-Passwort wird in den Einstellungen (Reiter 'Sicherheit') gesetzt werden. Beispiel: {"loginemail": "admin@somedomain.com", "apipassword": "12345678"}
Rückgabewert:
JSON Web Token
Das zurückgegebene Token muss bei jedem Request zur Authentifikation als Header mitgeschickt werden.

Ressource @GET /api/time-v2.1/timetypes

Parameter:
Keine
Rückgabewert:
[{id, name}, ...]
Die Liste der Zeitarten im Format: Id der Zeitart, Name der Zeitart. Beispiel: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Arbeitszeit"}, ...]

Ressource @GET /api/time-v2.1/users

Diese Ressource liefert eine Liste der Loginemails aller Benutzer zurück.

Parameter:
Keine
Rückgabewert:
[{loginemail}, ...]
Die Liste der Loginemails aller Benutzer. Beispiel: [{"admin@somedomain.com"}, ...]

Ressource @GET /api/time-v2.1/projects

Diese Ressource liefert die Liste der Projekte zurück.

Parameter:
Keine
Rückgabewert:
[{id, name}, ...]
Die Liste der Projekte im Format: Id des Projekts, Name des Projekts. Beispiel: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demoprojekt"}, ...]

Ressource @GET /api/time-v2.1/projects/{useremail}

Diese Ressource liefert eine Liste der Projekte für einen bestimmten Benutzer zurück.

Pfad-Parameter:
{useremail}
Die Loginemail des fraglichen Benutzers. Beispiel: @GET /projects/maier@somedomain.com
Rückgabewert:
[{id, name}, ...]
Die Liste der Projekte im Format: Id des Projekts, Name des Projekts. Beispiel: [{"id": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "name": "Demoprojekt"}, ...]

Ressource @GET /api/time-v2.1/timeentries?useremail={useremail}&start={start}&end={end}

Diese Ressource gibt die Zeiteinträge eines Benutzers für einen bestimmten Zeitraum zurück.

Abfrage-Parameter:
{useremail, start, end}
Es werden alle Zeiteinträge des Benutzers zurückgegeben, deren Startzeit zwischen start und end liegen. start und end müssen im folgenden Format angegeben werden: YYYY-MM-DDTHH:MM:00 also z.B.: 2024-12-24T17:03:00.

Beispiel für die Pfadparameter für eine Abfrage der Zeiteinträge über drei Tage:
useremail=maier@somedomain.com, start=2024-07-23T00:00:00, end=2024-07-25T23:59:00
Rückgabewert:
[{id, starttime, ...}, ...]
Die Liste der Zeiteinträge des Benutzers im angegebenen Zeitraum.

Beispiel für eine Liste der zurückgegebenen Zeiteinträge:
[{"id": "876b36db-2047-4f56-ab76-98221ca42600", "starttime": "2016-06-18T00:00:00", "endtime": "2016-06-19T00:00:00", "useremail": "admin@somedomain.com", "timetypeid": "56941eee-86a7-4a8d-8af1-f78b0a688f32", "projectid": "693fe9a3-bb48-4763-bb20-5fd9fa4ffeb2"}, ...]

Ressource @POST /api/time-v2.1/createtimeentry

Mit dieser Ressource kann man einen neuen Zeiteintrag erzeugen.

Parameter:
{starttime, endtime, useremail, timetypeid, projectid, comment}
starttime und endtime müssen im folgenden Format angegeben werden: YYYY-MM-DDTHH:MM:00 - z.B.: 2017-03-23T10:15:00.
Die Angabe einer projectid ist optional.
Die Angabe von comment ist optional.

Beispiel für einen neuen Zeiteintrag:
{"starttime": "2017-03-23T10:15:00", "endtime": "2017-03-23T18:21:00", "useremail": "maier@somedomain.com", "timetypeid": "83be5360-6067-4a09-a970-1ff2413d7101", "projectid": "2aeba501-ca09-41b2-a938-654d178914e4" "comment": "Eine Testbemerkung!"}
Rückgabewert:
[{id}, ...]
Die Liste der id's aller erzeugter Zeiteinträge. Die Liste enthält in den meisten Fällen nur einen einzigen Eintrag. Beispiel: [{"2b301fbc-9594-4bdf-abc4-6cd77714134d"}]

Ressource @DELETE /api/time-v2.1/deletetimeentry/{id}

Mit dieser Ressource kann man einen Zeiteintrag löschen.

Pfad-Parameter:
{id}
Die id des zu löschenden Zeiteintrages. Z.B.: 83be5360-6067-4a09-a970-1ff2413d7101

Rückgabewert:
Keiner
« Zurück zur Übersicht

© 2005 - 2025 Goodtime Online-Arbeitszeiterfassung - REST-Schnittstelle