ProSonata API

Arbeitszeiten

Folgende HTTP-Methoden stehen für Projektzeiten zur Verfügung:

Zugriff für alle Benutzergruppen.
Alle nicht-Administratoren erhalten nur ihre eigenen Arbeitszeiten.
Nur Administratoren können Arbeitszeiten aller Benutzer erstellen/bearbeiten/löschen.
Alle Benutzer können ihre eigenen Arbeitszeiten erstellen/bearbeiten/löschen.

alle Arbeitszeiten auflisten

GET /api/v1/workingtimes

Antwort:

{
  "meta": {
    "status": 200,
    "perPage": 100,
    "page": 1,
    "totalCount": 5612,
    "requestUserID": 1,
    "requestUsername": "Max",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 456,
    "apiLimitReset": 264
  },
  "data": [
    {
      "workingTimeID": 1,
      "userID": 3,
      "username": "Admin2",
      "userFirstName": "Max",
      "userLastName": "Mustermann",
      "workingDate": "2021-02-13",
      "dailyTimeStart": "09:15:00",
      "dailyTimeEnd": "17:10:00",
      "dayType": 0,
      "halfHoliday": 0,
      "homeOffice": 0,
      ...
    },
    ...
  ]
}

Filterung/Suche

Über Parameter kann gefiltert werden:

GET /api/v1/workingtimes?userID=3
Parameter Beschreibung
userID ID eines Benutzers
Sonderwert: String »myself« für Zeiten des anfragenden Benutzeraccounts
username Benutzername
workingDate Datum des Zeiteintrags
durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
workingDate2 zweite Datumsangabe, um die Suchanfrage weiter einzuschränken
durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
dayType Tagestyp
0 = Arbeit
1 = Urlaub
2 = Krankheit
3 = Feiertag
4 = Schule/Fortbildung
5 = Überstundenabbau
6 = Elternzeit / Mutterschutz / Pflegezeit / Sonstige
halfHoliday halber Tag Urlaub
0 = nein
1 = ja
homeOffice im Home-Office gearbeitet
0 = nein
1 = ja

 

Sortierung

Nach folgenden Parametern kann sortiert werden (Sortierrichtung ggf. mit ASC bzw. DESC ergänzen):

workingTimeID, userID, workingDate

eine Arbeitszeit aufrufen

GET /api/v1/workingtimes/{id}

Antwort:

{
  "meta": {
    "status": 200,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 495,
    "apiLimitReset": 462
  },
  "data": {
    "workingTimeID": 1,
    "userID": 3,
    "username": "Max",
    "userFirstName": "Max",
    "userLastName": "Mustermann",
    "workingDate": "2021-03-20",
    "dailyTimeStart": "09:15:00",
    "dailyTimeEnd": "17:10:00",
    "dayType": 0,
    "halfHoliday": 0,
    "homeOffice": 0,
    "break1Start": "12:00:00",
    "break1End": "12:30:00",
    "break2Start": null,
    "break2End": null,
    "dailyTimeTotal": 7.42,
    "comments": "",
    "editedByUserID": 0,
    "workingTimeCreationDate": null,
    "workingTimeViaApi": 0
  }
}

eine Arbeitszeit erstellen

POST /api/v1/workingtimes

Notwendige und mögliche Parameter im Body:

Parameter Beschreibung Typ Default-Wert Pflichtfeld
userID ID des Benutzers
(nur Administratoren können Zeiten
für andere Benutzer erfassen!)
Int   ja
workingDate Datum des Zeiteintrags Date   ja
dailyTimeStart Startzeitpunkt Time   ja
dailyTimeEnd Endzeitpunkt Time   ja
dayType Tagestyp
0 = Arbeit
1 = Urlaub
2 = Krankheit
3 = Feiertag
4 = Schule/Fortbildung
5 = Überstundenabbau
6 = Elternzeit / Mutterschutz / Pflegezeit / Sonstige
Int 0  
halfHoliday halber Tag Urlaub
0 = nein
1 = ja
Int 0  
homeOffice im Home-Office gearbeitet
0 = nein
1 = ja
Int 0  
break1Start Pause 1 Startzeit Time null  
break1End Pause 1 Endzeit Time null  
break2Start Pause 2 Startzeit Time null  
break2End Pause 2 Endzeit Time null  
dailyTimeTotal Gesamtzeit des Tages (in h) Dec   ja
comments Anmerkungen
(max. 100 Zeichen)
String    

Angabe von Dezimalwerten mit Punkt als Trennzeichen.

Wichtig: Die übergebenen Werte (Startzeitpunkt, Endzeitpunkt und die resultierende dailyTimeTotal) müssen korrekt berechnet sein. Sie werden bei der Übernahme durch die API nicht zusätzlich auf Richtigkeit geprüft!

Ist für den Benutzer an dem angegebenen Tag bereits ein Eintrag vorhanden, wird dieser Tageseintrag gelöscht und anschließend der neue Eintrag erstellt.

Beispiel:

{
    "userID": 1,
    "workingDate": "2021-03-02",
    "dailyTimeStart": "08:18:00",
    "dailyTimeEnd": "16:48:00",
    "dailyTimeTotal": 7.75,
    "break1Start": "12:06:00",
    "break1End": "12:51:00",
    "comments": "eine Anmerkung"
}

eine Arbeitszeit bearbeiten

PUT /api/v1/workingtimes/{id}

Es müssen nicht alle Parameter für eine Bearbeitung übergeben werden.

Es stehen die Parameter zum Erstellen der Ressource zur Verfügung. Die Werte userID und workingDate dürfen nicht verändert werden (um doppelte Einträge für einen Tag und Benutzer zu vermeiden). Bei Bedarf muss also ein Eintrag gelöscht und durch einen neuen Eintrag ersetzt werden.

eine Arbeitszeit löschen

DELETE /api/v1/workingtimes/{id}

Es müssen keine weiteren Parameter übergeben werden.