« 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. Hinweis: Das selbe Passwort wird auch für die Webservice-Schnittstelle verwendet.

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