Timebutler API Dokumentation

Timebutler bietet eine RESTful API, um Daten automatisiert abrufen und in Drittsystemen weiterverarbeiten zu können.

Aufruf der Schnittstelle

Die API kann mit einem HTTP POST Request abgefragt werden. Andere HTTP Methods wie GET, PUT, usw. sind aus Sicherheitsgründen nicht erlaubt und werden von der Schnittstelle abgelehnt. Die URL für alle Abfragen lautet:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/[...]

Das [...] am Ende der URL muss durch die gewünschte API-Aktion ersetzt werden. Gültige API-Aktions-Codes finden Sie weiter unten in dieser Dokumentation.

Die URL könnte also beispielsweise wie folgt lauten:

Beispiel:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/absences

Authentifizierung

Zur Authentifizierung muss bei jedem API-Aufruf der individuelle API-Token als HTTP Post Parameter übergeben werden:

Parametername	Wert
auth	Ihr individueller API-Token (API-Token abrufen )

Zwei API-Tokens

Beachten Sie, dass es zwei API-Tokens gibt:

Damit kann der Zugriff auf die Personalakte und Gehaltsdaten getrennt vom Zugriff auf die anderen Daten gesteuert und freigegeben oder verboten werden.

Für den Aufruf der folgenden Endpunkte verwenden Sie den API-Token für die Personalakte und Gehaltsdaten:

salariespersonnelfiles

Für alle weiteren Endpunkte verwenden Sie den anderen API-Token.

HTTP Antwort Codes

Bei jedem HTTP Post Request gibt die Schnittstelle einen der folgenden Codes zurück:

Code	Name	Beschreibung
200	OK	All good, response contains requested data.
400	Bad request	The request was invalid, e.g. the action code does not exist or is invalid
401	Unauthorized	Authentication information missing or invalid or API access has been deactivated by user
404	Not found	Invalid URL, Version in request URL not supported, malformed URL
405	Method not allowed	Invalid HTTP method for the API URL
413	Request Entity Too Large	The number of bytes of the uploaded data is larger than the allowed amount (3 MB).
500	Internal server error	Internal server error, please retry later

Aktionen - Übersicht

Durch Übergabe des API-Aktions-Codes in der URL können verschiedene API-Funktionen aufgerufen werden. Diese sind:

API-Aktion	Beschreibung und URL
absences	Abwesenheitseinträge auslesen Liefert eine Liste aller Abwesenheitseinträge aller Nutzer zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/absences
useraccount	Nutzerkonto bearbeiten Endpunkt zum Bearbeiten von Nutzerkonten. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/useraccount
managerassignment	Vorgesetzten-Zuordnung ändern Endpunkt zum Ändern der Zuordnung der Mitarbeiter zu den Vorgesetzten https://personalmanagement.ulb.tu-darmstadt.de/api/v1/managerassignment
users	Nutzerdaten auslesen Liefert eine Liste aller Nutzer zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/users
holidayentitlement	Urlaubsanspruchsdaten auslesen Liefert eine Liste aller Urlaubsanspruch-Werte aller Nutzer für ein bestimmtes Jahr zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidayentitlement
setholidayentitlement	Urlaubsanspruchsdaten ändern Endpunkt zum Ändern der Urlaubsanspruchsdaten eines Mitarbeiters https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setholidayentitlement
workdays	Arbeitstage der Nutzer auslesen Liefert eine Liste der Arbeitstage der Nutzer zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/workdays
setworkdays	Arbeitstage der Nutzer ändern Endpunkt zum Ändern der Arbeitstage der Nutzer eines Mitarbeiters https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setworkdays
holidaysets	Feiertagsregelungen auslesen Liefert eine Liste der Feiertagsregelungen zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidaysets
worktime	Arbeitszeiteinträge der Nutzer auslesen Liefert eine Liste der Arbeitszeiteinträge der Nutzer zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktime
projects	Liste der Projekte auslesen Liefert eine Liste aller konfigurierten Projekte (Zeiterfassung) zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projects
projectsimport	Projekte hinzufügen, ändern oder löschen Die bestehende Liste der Projekte kann damit erweitert oder geändert werden. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projectsimport
services	Liste der Kategorien auslesen Liefert eine Liste aller konfigurierten Kategorien (Zeiterfassung) zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/services
worktimeaccountinperiod	Abfrage der Arbeitszeitkonten - Arbeitszeit im Zeitraum Liefert die Daten der Arbeitszeitkonten in der Ansicht "Arbeitszeit im Zeitraum" zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountinperiod
worktimeaccountbalance	Abfrage der Arbeitszeitkonten - Überstundenstand zum Stichtag Liefert die Daten der Arbeitszeitkonten in der Ansicht "Überstundenstand zum Stichtag" zurück. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountbalance
timeclock	Virtuelle Stempeluhr steuern Stellt Kommandos zum Starten, Pausieren und Stoppen der virtuellen Stempeluhr bereit. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeclock
timeimportbyevents	Import von Arbeitszeiteinträgen Zum Import von Arbeitszeiteinträgen nach Timebutler, die von Zeiterfassungsterminals von Drittanbietern aufgezeichnet wurden. Import der Stempeluhr-Ereignisse (Start/Pause/Stop/...) https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeimportbyevents
personnelfiles	Personalakte abfragen Zur Abfrage von Daten aus der digitalen Personalakte. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/personnelfiles
salaries	Gehaltsdaten abfragen Zur Abfrage von Gehaltsdaten der Mitarbeiter. https://personalmanagement.ulb.tu-darmstadt.de/api/v1/salaries

Aktion absences

Mit dieser Aktion werden alle Abwesenheitseinträge aller Nutzer eines bestimmten Jahres zurückgeliefert. Wenn das gewünschte Jahr nicht übergeben wird, werden die Einträge des aktuellen Jahres zurückgegeben.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/absences

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
year	Nein	Kalenderjahr im Format JJJJ, beispielsweise 2023. Falls nicht angegeben, wird das aktuelle Kalenderjahr verwendet.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Abwesenheitseinträge. Die Daten sind mit einem Semikolon separiert. Sind keine Einträge für das Jahr vorhanden, wird nur die erste Zeile mit den Spaltenüberschriften zurückgegeben.

Die Spalte "Type" beinhaltet den Namen des Abwesenheitstyps. Ein Admin kann beliebige Abwesenheitstypen konfigurieren. Sie können die Liste der Abwesenheitstypen aufrufen, indem Sie sich als Admin anmelden, dann links unten auf "Einstellungen" klicken, dann darunter auf "Weitere..", dann rechts auf "Abwesenheitstypen".

Zusatzfelder

Für jeden Abwesenheitstyp können individuell Zusatzfelder konfiguriert werden. Beispielsweise kann für den Abwesenheitstyp "Dienstreise" ein Zusatzfeld "Zielort" (Text), "Entfernung in km" (Zahl), "Reisekosten Betrag" (Kommazahl) und "Tag der Beantragung" (Datum) festgelegt werden. Die Nutzer können dann bei Eintragung einer Dienstreise die Angaben zu den Zusatzfeldern eintragen.

Bei den Rückgabe-Daten werden dann weitere Spalten ausgegeben: für jeden Abwesenheitstyp eine Spalte "Zusatzfelder für <Abwesenheitstyp>" und anschließend für jedes Zusatzfeld eine eigene Spalte.

Beispiel:

Wenn für den Abwesenheitstyp "Dienstreise" die Zusatzfelder "Zielort" und "Entfernung in km" konfiguriert sind und für den Abwesenheitstyp "Weiterbildung" die Zusatzfelder "Kursname" und "Kursgebühr" konfiguriert sind, dann werden nach den Spalten der oben genannten Rückgabe-Daten zusätzlich auch Spalten mit den folgenden Überschriften zurückgegeben:

Aktion useraccount

Mit dieser Aktion kann ein neues Nutzerkonto erstellt werden, ein bestehendes Nutzerkonto geändert, gesperrt oder gelöscht werden oder die Email-Adresse eines bestehenden Nutzerkontos geändert werden.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/useraccount

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe beim Erstellen eines Nutzerkontos	Pflichtangabe beim Update / Sperren / Löschen eines Nutzerkontos	Pflichtangabe beim Ändern der Email- Adresse	Wert
command	Ja	Ja	Ja	Die gewünschte Aktion, die ausgeführt werden soll. Die möglichen Kommandos lauten: create update modifyemail unlock lock delete Details anzeigen
email	Ja	Ja: email oder employeenumber oder userid	Ja: email oder employeenumber oder userid	Die Email-Adresse des Nutzerkontos, das erstellt oder geändert werden soll.
employeenumber	Optional	Ja: email oder employeenumber oder userid	Ja: email oder employeenumber oder userid	Die Mitarbeiter-Nummer des Nutzerkontos, das geändert werden soll.
userid	Nein: muss leer bleiben oder nicht übergeben werden	Ja: email oder employeenumber oder userid	Ja: email oder employeenumber oder userid	Die eindeutige userid des Nutzerkontos, das geändert werden soll. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.
first_name	Ja	Nein	Nein	Der Vorname des Mitarbeiters, max. 50 Zeichen
lastname	Ja	Nein	Nein	Der Nachname des Mitarbeiters, max. 50 Zeichen
title	Nein	Nein	Nein	Der Titel des Mitarbeiters, beispielsweise Dr. oder Prof., max. 50 Zeichen
new_email	Nein	Nein	Ja	Die neue Email-Adresse für das Nutzerkonto. Diese Angabe ist nur beim command modifyemail notwendig.
gender	Ja	Nein	Nein	Parameterwert Bedeutung 0 Frau 1 Herr 2 Divers
location	Nein	Nein	Nein	Der Standort des Mitarbeiters, max. 50 Zeichen
unit	Nein	Nein	Nein	Die Abteilung des Mitarbeiters, max. 50 Zeichen
phone	Nein	Nein	Nein	Die Telefonnummer des Mitarbeiters, max. 50 Zeichen
mobile_phone	Nein	Nein	Nein	Der Mobiltelefonnummer des Mitarbeiters, max. 50 Zeichen
cost_unit	Nein	Nein	Nein	Die Kostenstelle des Mitarbeiters, max. 20 Zeichen
additional_info	Nein	Nein	Nein	Beliebige Zusatzinformation zum Mitarbeiter / Nutzerkonto, max. 500 Zeichen
date_of_birth	Nein	Nein	Nein	Geburtsdatum des Mitarbeiters im Format yyyy-mm-dd (beispielsweise 1987-06-26)
date_of_entry	Nein	Nein	Nein	Eintrittsdatum im Unternehmen des Mitarbeiters im Format yyyy-mm-dd (beispielsweise 2019-03-15)
date_of_separation	Nein	Nein	Nein	Austrittsdatum aus dem Unternehmen des Mitarbeiters im Format yyyy-mm-dd (beispielsweise 2024-12-31)
timetrack_startdate	Nein	Nein	Nein	Startdatum für die Zeiterfassung im Format yyyy-mm-dd (beispielsweise 2024-03-15). Wenn das Zeiterfassungsfeature im Timebutler nicht aktiviert ist, dann hat dieses Datum keine Auswirkung. Falls nicht angegeben, dann gilt das Standard Startdatum der Zeiterfassung, das für alle Mitarbeiter gilt. Ausnahme: falls ein Eintrittsdatum angegeben ist und kein Startdatum für die Zeiterfassung, dann wird das Eintrittsdatum auch als Startdatum für die Zeiterfassung gesetzt.
timetrack_earliest_time	Nein	Nein	Nein	Frühste Startuhrzeit für die Zeiterfassung im Format hh:mm (beispielsweise 07:00 für die früheste Startuhrzeit um 7 Uhr am Morgen). Erlaubt sind die Werte im 5-Minuten-Takt: 00:05, 00:10, 00:15, usw. bis 23:55. Wenn das Zeiterfassungsfeature im Timebutler nicht aktiviert ist, dann hat diese Angabe keine Auswirkung. Falls nicht angegeben, dann gilt der Standardwert für die früheste Startuhrzeit, die für alle Mitarbeiter gilt.
locale	Ja	Nein	Nein	Locale (Sprache, Land) des Mitarbeiters. Wird beim Versenden von Emails an den Nutzer verwendet, um die Email in der passenden Sprache zu verschicken. Parameterwert Bedeutung de_DE Deutsch en_UK Englisch en_US Englisch (US)
user_type	Ja	Ja (nur beim Update)	Nein	Der Nutzertyp für das Nutzerkonto. Parameterwert Bedeutung employee Mitarbeiter Nutzerkonto manager Vorgesetzten Nutzerkonto admin Administrator Nutzerkonto

Rückgabe-Daten

Im Response wird einer der folgenden Ergebniswerte zurückgegeben:

Ergebniswerte anzeigen >

Aktion managerassignment

Mit dieser Aktion können die Vorgesetzten für ein Nutzerkonto festgelegt werden.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/managerassignment

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
email	Ja: email oder employeenumber oder userid	Die Email-Adresse des Nutzerkontos, dessen Vorgesetzte geändert werden sollen.
employeenumber	Ja: email oder employeenumber oder userid	Die Mitarbeiter-Nummer des Nutzerkontos, dessen Vorgesetzte geändert werden sollen.
userid	Ja: email oder employeenumber oder userid	Die eindeutige userid des Nutzerkontos, dessen Vorgesetzte geändert werden sollen. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.
manager1	Ja	Die userid des Nutzers, der als 1. Vorgesetzter festgelegt werden soll.
manager2	Nein	Die userid des Nutzers, der als 2. Vorgesetzter festgelegt werden soll.
manager3	Nein	Die userid des Nutzers, der als 3. Vorgesetzter festgelegt werden soll.
...	...	...
manager10	Nein	Die userid des Nutzers, der als 10. Vorgesetzter festgelegt werden soll.

Rückgabe-Daten

Im Response wird einer der folgenden Ergebniswerte zurückgegeben:

Ergebniswerte anzeigen >

Aktion users

Mit dieser Aktion werden die Daten aller Nutzer zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/users

Request-Parameter

Es sind keine zusätzlichen Parameter möglich oder erforderlich.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Nutzerdaten. Die Daten sind mit einem Semikolon separiert.

Aktion holidayentitlement

Mit dieser Aktion werden die Urlaubsanspruchsdaten der Nutzer für ein bestimmtes Jahr zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidayentitlement

Request-Parameter

Folgender Parameter kann als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
year	Nein	Kalenderjahr im Format JJJJ, beispielsweise 2023. Falls nicht angegeben, wird das aktuelle Kalenderjahr verwendet.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Werte des Urlaubsanspruchs. Die Daten sind mit einem Semikolon separiert.

Aktion setholidayentitlement

Mit dieser Aktion können die Urlaubsanspruchswerte für einen Nutzer geändert werden.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setholidayentitlement

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
email	Ja: email oder employeenumber oder userid	Die Email-Adresse des Nutzerkontos, dessen Urlaubsanspruchswerte geändert werden sollen.
employeenumber	Ja: email oder employeenumber oder userid	Die Mitarbeiter-Nummer des Nutzerkontos, dessen Urlaubsanspruchswerte geändert werden sollen.
userid	Ja: email oder employeenumber oder userid	Die eindeutige userid des Nutzerkontos, dessen Urlaubsanspruchswerte geändert werden sollen. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.
year	Ja	Das Jahr, für das der Urlaubsanspruch geändert werden soll.
holiday_entitlement	Nein	Anzahl Tage für den Urlaubsanspruch (Format nn.n, beispielsweise 25.5)
remaining_leave	Nein	Anzahl Tage für den Resturlaub aus dem Vorjahr (Format nn.n, kann auch negativ sein, beispielsweise -3.5)
special_leave	Nein	Anzahl Tage für den Sonderurlaub (Format nn.n, beispielsweise 2.5)
severely_challenged_persons_leave	Nein	Anzahl Tage für den Schwerbehindertenurlaub (Format nn.n, beispielsweise 6.5)
other_leave	Nein	Anzahl Tage für den weiteren Urlaubsanspruchstyp (Format nn.n, beispielsweise 1.5). Ein Admin kann einen weiteren Urlaubsanspruchstyp aktivieren und diesem Anspruchstyp eine beliebige Bezeichnung geben (beispielsweise "Regenerationstage").
expired_leave	Nein	Anzahl Tage für den verfallenen Urlaubsanspruch (Format nn.n, beispielsweise 2.5)
paid_out_leave	Nein	Anzahl Tage für den ausbezahlten Urlaubsanspruch (Format nn.n, beispielsweise 8.5)
five_day_week_entitlement	Nein	Anzahl Tage Urlaubsanspruch, die der Mitarbeiter bei einer 5-Tage-Woche hätte (Format nn.n, beispielsweise 8.5, darf nicht negativ sein). Mit diesem Wert wird bei Änderung von Eintrittsdatum/Austrittsdatum oder Änderung der Wochenarbeitstage der neue Urlaubsanspruch berechnet (nur bei Änderung durch einen Nutzer, nicht durch die API). Es gibt nur einen Wert, der für alle Jahre gültig ist. Aus technischen Gründen muss dennoch bei diesem API-Aufruf ein gültiger Wert für den Parameter year übergeben werden, beispielsweise das aktuelle Jahr.

Rückgabe-Daten

Im Response wird einer der folgenden Ergebniswerte zurückgegeben:

Ergebniswerte anzeigen >

Aktion workdays

Mit dieser Aktion werden die Arbeitstage aller Nutzer zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/workdays

Request-Parameter

Es sind keine zusätzlichen Parameter möglich oder erforderlich.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Arbeitstage der Nutzer. Die Daten sind mit einem Semikolon separiert. Da ein Nutzer mehrere Arbeitstag-Einstellungen eingestellt haben kann, können in den zurückgelieferten CSV-Daten mehrere Zeilen mit der gleichen User ID beinhaltet sein.

Aktion setworkdays

Mit dieser Aktion können die Arbeitstage, die Soll-Arbeitszeit und die Feiertagsregelung für einen Nutzer geändert werden.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/setworkdays

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
email	Ja: email oder employeenumber oder userid	Die Email-Adresse des Nutzerkontos, dessen Arbeitstage geändert werden sollen.
employeenumber	Ja: email oder employeenumber oder userid	Die Mitarbeiter-Nummer des Nutzerkontos, dessen Arbeitstage geändert werden sollen.
userid	Ja: email oder employeenumber oder userid	Die eindeutige userid des Nutzerkontos, dessen Arbeitstage geändert werden sollen. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.
group_NN_valid_from1)	Ja	Datum ab dem die folgenden Einstellungen gelten sollen, im Format yyyy-mm-dd (beispielsweise 2024-05-01). Der erste Parameter group_1_valid_from hat immer den Wert 0 (=gültig von Beginn an). Darauf folgende Werte group_2_valid_from, group_3_valid_from, usw. müssen Datumswerte haben, die zeitlich aufsteigend geordnet sind (beispielsweise 2024-05-01, dann 2024-11-15, usw.). Die Datumswerte für den Beginn des nächsten Zeitraums sind automatisch das Ende des vorangehenden Zeitraums. Beispiel: ein Wert group_2_valid_from = 2024-05-01 bedeutet, dass der zweite Zeitraum am 2024-05-01 startet und automatisch auch, dass der vorangehende, erste Zeitraum am 2024-04-30 endet.
group_NN_working_time_mo1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Montag (0=kein Arbeitstag)
group_NN_working_time_tu1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Dienstag (0=kein Arbeitstag)
group_NN_working_time_we1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Mittwoch (0=kein Arbeitstag)
group_NN_working_time_th1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Donnerstag (0=kein Arbeitstag)
group_NN_working_time_fr1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Freitag (0=kein Arbeitstag)
group_NN_working_time_sa1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Samstag (0=kein Arbeitstag)
group_NN_working_time_su1)	Ja	Soll-Arbeitszeit in Minuten für den Wochentag Sonntag (0=kein Arbeitstag)
group_NN_holiday_set_id1)	Ja	ID der Feiertagsregelung, die für den angegebenen Zeitraum gelten soll. Die Liste der IDs der Feiertagsregelungen erhalten Sie über den API-Aufruf holidaysets (siehe hier).
group_NN_overtime_transfer_type1)	Nein	Regel zur Berechnung der Anzahl abgegoltener Überstunden je Monat. Folgende Werte sind erlaubt: Parameterwert / Bedeutung transfer_all (Standardwert) Alle Überstunden in den nächsten Monat übertragen. transfer_none Alle Überstunden sind abgegolten, weder Überstunden noch Minusstunden in den nächsten Monat übertragen (das Überstundensaldo bleibt also immer gleich). transfer_over_limit_only Die Überstunden eines Monats sind bis zu einer bestimmten Anzahl abgegolten. Die Grenze kann im Parameter group_NN_overtime_limit_mins übergeben werden. transfer_until_limit_only Es werden maximal bis zu einer bestimmten Anzahl Überstunden eines Monats in den nächsten Monat übertragen. Die Grenze kann im Parameter group_NN_overtime_limit_mins übergeben werden. max_value_start_of_month Der Überstundenstand am ersten Tag jedes Monats soll maximal einen bestimmten Wert betragen dürfen. Bei Überschreitung werden die Überstunden gekürzt. Die Grenze kann im Parameter group_NN_overtime_limit_mins übergeben werden.
group_NN_overtime_limit_mins1)	Nur wenn group_NN_overtime_transfer_type einen der folgenden Werte hat: transfer_over_limit_only transfer_until_limit_only max_value_start_of_month	Die Grenze für die gewählte Überstunden-Übertragung in Minuten (beispielsweise 120 = 2 Stunden). Wenn der Wert übergeben wird, muss er größer als 0 sein.
group_NN_round_down_mins1)	Nein	Angabe in Minuten. Die Arbeitszeit wird abgerundet, wenn die Soll-Arbeitszeit um maximal die in diesem Parameter angegebene Anzahl Minuten überschritten wurde. Wert 0 oder Parameter nicht übergeben: keine Rundung.
group_NN_round_up_mins1)	Nein	Angabe in Minuten. Die Arbeitszeit wird aufgerundet, wenn die Soll-Arbeitszeit um maximal die in diesem Parameter angegebene Anzahl Minuten unterschritten wurde. Wert 0 oder Parameter nicht übergeben: keine Rundung.
group_NN_setup_time_mins1)	Nein	Angabe in Minuten. Wenn die Zahl negativ ist: für jeden Kalendertag mit geleisteter Arbeitszeit wird die in diesem Parameter angegebene Anzahl Minuten als Rüstzeit von der geleisteten Arbeitszeit abgezogen. Angabe in Minuten. Wenn die Zahl positiv ist: für jeden Kalendertag mit geleisteter Arbeitszeit wird die in diesem Parameter angegebene Anzahl Minuten als Rüstzeit zu der geleisteten Arbeitszeit hinzugefügt. Wert 0 oder Parameter nicht übergeben: keine Rüstzeiten.

¹⁾ Information zu den Parametern group_NN_..

Bei den oben genannten Parametern muss das NN durch eine Zahl 1 - 99 ersetzt werden. Damit können Sie bis zu 99 Zeiträume festlegen und für jeden Zeitraum die Wochenarbeitstage und Feiertage festlegen. Alle Parameter, die mit der gleichen Zahl beginnen (beispielsweise group_1_..) gehören somit zu einer Gruppe, mit der die Einstellungen für den Zeitraum festgelegt werden.

• Wenn Sie nur einen Zeitraum festlegen möchten, dann übergeben Sie nur die Parameter group_1_valid_from bis group_1_holiday_set_id (und wenn gewünscht die Parameter für die Zeiterfassung).
• Wenn Sie zwei Zeiträume festlegen möchten, dann übergeben Sie
  • die Parameter group_1_valid_from bis group_1_holiday_set_id (und wenn gewünscht die Parameter für die Zeiterfassung).
  • und die Parameter group_2_valid_from bis group_2_holiday_set_id (und wenn gewünscht die Parameter für die Zeiterfassung).

Es können somit bis zu 99 Zeiträume übergeben werden (group_1_... bis group_99_...).

Detaillierte Beispiele anzeigen >

Rückgabe-Daten

Im Response wird einer der folgenden Ergebniswerte zurückgegeben:

Ergebniswerte anzeigen >

Aktion holidaysets

Mit dieser Aktion wird die Liste aller Feiertagsregelungen zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/holidaysets

Request-Parameter

Es sind keine zusätzlichen Parameter möglich oder erforderlich.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die eindeutige ID und der Name der Feiertagsregelung, die mit einem Semikolon separiert sind.

Aktion worktime

Mit dieser Aktion werden die Arbeitszeiteinträge aller Nutzer eines bestimmten Monats zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktime

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
year	Nein	Kalenderjahr im Format JJJJ, beispielsweise 2023. Falls nicht angegeben, wird das aktuelle Kalenderjahr verwendet.
month	Nein	Monatszahl, Wert zwischen 1 und 12, beispielsweise 2 für Februar. Falls nicht angegeben, wird der aktuelle Monat verwendet.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Arbeitszeiteinträge der Nutzer. Die Daten sind mit einem Semikolon separiert.

Aktion projects

Mit dieser Aktion wird die Liste aller konfigurierten Projekte aus den Einstellungen für die Zeiterfassung zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projects

Request-Parameter

Es sind keine zusätzlichen Parameter möglich oder erforderlich.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Abwesenheitseinträge. Die Daten sind mit einem Semikolon separiert. Sind keine Einträge für das Jahr vorhanden, wird nur die erste Zeile mit den Spaltenüberschriften zurückgegeben.

Aktion projectsimport

Mit dieser Aktion können neue Projekte in die Liste der Projekte importiert und bestehende Projekte geändert oder gelöscht werden.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/projectsimport

Request-Parameter

Folgender Parameter muss übergeben werden:

Parametername	Typ	Wert
csvdatafile	File	Datei mit den zu importierenden Daten im CSV-Format. Details zum Aufbau der Daten siehe weiter unten.

Aufbau der CSV-Datei

In der CSV-Datei werden die Projekt-Informationen übergeben. Je Zeile in der CSV-Datei wird ein Kommando für ein Projekt übergeben. Je Zeile kann also ein Projekt hinzugefügt oder geändert oder gelöscht werden. Die CSV darf keine Kopfzeilen beinhalten, sondern alle Zeilen ab der ersten Zeile werden verarbeitet und importiert. Dass Trennzeichen der Daten in einer Zeile der CSV-Datei ist das Semikolon (;).

In jeder Zeile der CSV-Datei müssen folgende Daten in den Spalten übergeben werden:

Spalte / Wert	Beschreibung	Format / Beispiele
Erste Spalte Eines der Kommandos CREATE UPDATE DELETE	Mit diesem Wert legen Sie fest, was mit den übergebenen Daten in der Zeile geschehen soll: CREATE Es wird ein neues Projekt erstellt und gespeichert. UPDATE Bestehendes Projekt ändern: In der Zeile muss die ID des zu ändernden Projekts übergeben werden (siehe Beschrebung zur nächsten Spalte). Falls es zu der ID ein Projekt gibt, dann werden die Angaben zum Projekt geändert. Falls es zu der ID kein Projekt gibt, dann wird eine Fehlermeldung zurückgegeben und die CSV-Zeile verworfen. DELETE Bestehendes Projekt löschen: In der Zeile muss die ID des zu löschenden Projekts übergeben werden (siehe Beschrebung zur nächsten Spalte). Falls es zu der ID ein Projekt gibt, dann wird das Projekt gelöscht (falls es mindestens einen Arbeitszeit zu dem Projekt gibt, wird das Projekt nicht gelöscht und eine Fehlermeldung zurückgegeben). Falls es kein Projekt gibt, wird keine Aktion ausgeführt und es wird auch keine Fehlermeldung zurückgegeben.	Eines der 3 Kommandos. Beispiele: CREATE DELETE
Zweite Spalte ID des Projekts	Die ID des Projekts, das geändert oder gelöscht werden soll. Die Angabe der ID ist bei allen Kommandos obligatorisch mit Ausnahme von CREATE (in diesem Fall wird eine möglicherweise übergebene ID ignoriert). Die Liste der von Timebutler vergebenen Projekt-IDs kann über den Endpunkt projects abgerufen werden.	Die ID des Projekts Beispiele: 4711 2367
Dritte Spalte Name des Projekts	Der Name des Projekts, das erstellt werden soll (Kommando CREATE) bzw. der neue Name des Projekts (Kommando UPDATE). Diese Spalte kann beim Kommando DELETE leer bleiben. Es sind maximal 150 Zeichen erlaubt. Zeilenumbrüche (Carriage Return oder Line Feed) sind nicht erlaubt, ebenso ist ein Semikolon nicht erlaubt, da dieses als Trennzeichen der CSV-Datei dient.	Der Name des Projekts, alphanumerisch Beispiele: Pegasus Zeus II
Vierte Spalte Projekt aktiv? true false	Die Angabe, ob das Projekt aktiv (neue Zeiteinträge für das Projekt erlaubt) oder inaktiv (neue Zeiteinträge für das Projekt nicht erlaubt) ist.	Einer der beiden Werte: true false
Fünfte Spalte Projekt-Budget in ganzen Stunden	Die Anzahl Stunden für das Projekt-Budget. Die Angabe ist optional. Wenn angegeben, muss der Wert eine Ganzzahl größer oder gleich 0 sein.	Das Projektbudget in Stunden als ganze Zahl Beispiele: 32 1200
Sechste Spalte Auswahl einer Kategorie Pflicht? true false	Die Angabe, ob die Nutzer bei Zeiteinträgen auf dieses Projekt auch eine Kategorie auswählen müssen oder nicht.	Einer der beiden Werte: true false
Siebte Spalte Kommentar	Ein Kommentar als interner Vermerk. Wird nur Admin-Nutzern bei der online Bearbeitung der Projektliste angezeigt. Wird anderen Nutzern, die Arbeitszeiten auf Projekte buchen, nicht angezeigt. Die Angabe ist optional. Es sind maximal 200 Zeichen erlaubt. Zeilenumbrüche (Carriage Return oder Line Feed) sind nicht erlaubt, ebenso ist ein Semikolon nicht erlaubt, da dieses als Trennzeichen der CSV-Datei dient.	Ein Kommentar für das Projekt als Text. Beispiel: Das wichtigste Projekt in diesem Jahr.

Bedingungen an die CSV-Datei

• Je Zeile darf nur ein Kommando mit Projektdaten übergeben werden
• Beim Kommando DELETE ist nur die Angabe der ID notwendig, alle anderen Spalten können leer bleiben. Es muss jedoch die vollständige Anzahl Spalten übergeben werden, somit also die richtige Anzahl Semikolons in der Zeile beinhaltet sein.
• Keine Kopfzeilen, alle Zeilen beinhalten nur Daten, keine Überschriftenzeile
• Spalteninhalte zwischen den Semikolons dürfen nicht in Hochkommata eingeschlossen werden (bzw. die Hochkommata werden wie übergeben eingelesen und verarbeitet)
• Die CSV-Datei darf maximal 9216000 Bytes groß sein.

CSV-Datei Beispiel

Ein Projekt "Pegasus IV" erstellen, das Projekt mit der ID 4711 ändern und das Projekt mit der ID 2367 löschen:

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben.

Wenn fehlende oder falsche Input-Daten übergeben wurden oder die übergebenen Daten nicht verarbeitet werden konnten, dann wird in der Antwort lediglich eine Zeile mit einem Fehlercode zurückgegeben, beispielsweise CSV_FILE_MISSING_OR_INVALID oder CSV_FILE_TOO_LARGE.

Wenn lesbare Daten übergeben wurden und die Input-CSV-Datei abgearbeitet werden kann, dann wird für jede übergebene Zeile der Input-CSV-Datei in der Antwort eine Zeile mit einer Rückmeldung zu der Verarbeitung der Zeile zurückgegeben.

Wenn die Input-Zeile erfolgreich verarbeitet werden konnte, dann steht in der Antwort-CSV ein Eintrag im folgenden Format:

Wenn die Input-Zeile nicht verarbeitet werden konnte, dann steht in der Antwort-CSV ein Eintrag im fogenden Format:

• Bei dem "#n" wird das "n" mit der Zeilennummer ersetzt.
• Das [PROJEKT-ID] wird mit der Projekt-ID des erstellten / geänderten / gelöschten Projekts ersetzt.
• Das [FEHLERCODE] wird mit einem der Fehlercodes ersetzt (siehe unten).

Die Rückgabe für eine Input-CSV-Datei mit 5 Zeilen könnte also beispielsweise wie folgt aussehen:

Fehler-Codes

Die Liste der möglichen Fehlercodes lautet:

Aktion services

Mit dieser Aktion wird die Liste aller konfigurierten Kategorien aus den Einstellungen für die Zeiterfassung zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/services

Request-Parameter

Es sind keine zusätzlichen Parameter möglich oder erforderlich.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Abwesenheitseinträge. Die Daten sind mit einem Semikolon separiert. Sind keine Einträge für das Jahr vorhanden, wird nur die erste Zeile mit den Spaltenüberschriften zurückgegeben.

Aktion worktimeaccountinperiod

Mit dieser Aktion werden die Daten aller Nutzer aus den Arbeitszeitkonten in der Ansicht "Arbeitszeit im Zeitraum" zurückgegeben.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountinperiod

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
startdate	Ja	Startdatum für den Zeitraum, aus dem die Arbeitszeit berechnet werden soll. Format: yyyy-mm-dd (z. B. 2024-07-15)
enddate	Ja	Enddatum für den Zeitraum, aus dem die Arbeitszeit berechnet werden soll. Das Enddatum darf nicht vor dem Startdatum liegen. Das Enddatum muss im gleichen Kalenderjahr wie das Startdatum liegen oder spätestens im nachfolgenden Kalenderjahr. Format: yyyy-MM-dd (z. B. 2024-08-31)
minutes	Nein	Wert: true oder false oder leer lassen/nicht übergeben. Bei dem API-Abruf werden verschiedene Zeit-Werte zurückgegeben, beispielsweise die Soll-Arbeitszeit oder die geleistete Arbeitszeit und das Saldo. Die Zeit-Werte weden im Industrieminuten-Format zurückgegeben, also im Format "hh.mm h" (beispielsweise "7.5 h" für 7 Stunden und 30 Minuten). Wenn bei dem API-Abruf ein Parameter minutes=true übergeben wird, dann werden die Zeit-Werte stattdessen in Minuten zurückgegeben. Statt beispielsweise "7.5 h" wird "450" zurückgegeben (450 Minuten = 7 h und 30 Minuten).

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Daten des Arbeitszeitkontos. Die Daten sind mit einem Semikolon separiert. Sind keine Daten vorhanden, wird nur die erste Zeile mit den Spaltenüberschriften zurückgegeben.

Spalten und Anordnung

Die erste Spalte beinhaltet die userid des Nutzerkontos, mit der das Nutzerkonto eindeutig identifiziert werden kann.

Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.

Die Liste und Anordnung der restlichen Spalten sind identisch mit den Spalten, wenn ein Nutzer in seinem Timebutler Nutzerkonto die Ansicht der Arbeitszeitkonten aufruft und auf den Button "Arbeitszeit im Zeitraum" klickt, siehe dort.

Aktion worktimeaccountbalance

Mit dieser Aktion werden die Daten aller Nutzer aus den Arbeitszeitkonten in der Ansicht "Überstundenguthaben zum Stichtag" zurückgegeben.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/worktimeaccountbalance

Request-Parameter

Folgende Parameter können als HTTP Post Parameter übergeben werden:

Parametername	Pflichtangabe	Wert
date	Ja	Das Datum, für das die Überstundenguthaben berechnet werden sollen. Format: yyyy-mm-dd (z. B. 2024-07-15)
minutes	Nein	Wert: true oder false oder leer lassen/nicht übergeben. Bei dem API-Abruf werden verschiedene Zeit-Werte zurückgegeben, beispielsweise die Soll-Arbeitszeit oder die geleistete Arbeitszeit und das Saldo. Die Zeit-Werte weden im Industrieminuten-Format zurückgegeben, also im Format "hh.mm h" (beispielsweise "7.5 h" für 7 Stunden und 30 Minuten). Wenn bei dem API-Abruf ein Parameter minutes=true übergeben wird, dann werden die Zeit-Werte stattdessen in Minuten zurückgegeben. Statt beispielsweise "7.5 h" wird "450" zurückgegeben (450 Minuten = 7 h und 30 Minuten).

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Daten des Arbeitszeitkontos. Die Daten sind mit einem Semikolon separiert. Sind keine Daten vorhanden, wird nur die erste Zeile mit den Spaltenüberschriften zurückgegeben.

Spalten und Anordnung

Die erste Spalte beinhaltet die userid des Nutzerkontos, mit der das Nutzerkonto eindeutig identifiziert werden kann.

Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.

Die Liste und Anordnung der restlichen Spalten sind identisch mit den Spalten, wenn ein Nutzer in seinem Timebutler Nutzerkonto die Ansicht der Arbeitszeitkonten aufruft und auf den Button "Überstundenguthaben zum Stichtag" klickt, siehe dort.

Aktion timeclock

Mit dieser Aktion können Sie Kommandos übergeben, um die virtuelle Stempeluhr eines Nutzers zu starten, zu pausieren (und fortzusetzen), zu stoppen oder die Aufzeichnung abzubrechen.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeclock

Request-Parameter

Folgende Parameter müssen als HTTP Post Parameter übergeben werden:

Parametername	Wert
command	Das gewünschte Kommando für die virtuelle Stempeluhr. Die möglichen Kommandos lauten: start Virtuelle Stempeluhr starten. Wenn die Stempeluhr pausiert ist, dann wird die Pause beendet und die Stempeluhr läuft weiter. Somit ist dieses Kommando gleichbedeutend mit dem Kommando "resume". pause Virtuelle Stempeluhr pausieren resume Pause beenden und Aufzeichnung fortsetzen. Wenn die Stempeluhr nicht pausiert ist, dann wird die Stempeluhr dennoch gestartet. Somit ist dieses Kommando gleichbedeutend mit dem Kommando "start". stop Virtuelle Stempeluhr stoppen und Zeiteintrag speichern cancel Virtuelle Stempeluhr stoppen und Zeiteintrag nicht speichern status Den aktuellen Status der virtuellen Stempeluhr abfragen (Stempeluhr ruht, Stempeluhr läuft, Pausiert)
userid	Die userid, mit der das Nutzerkonto eindeutig identifiziert werden kann. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.
projectid (optional)	Die ID des Projekts, auf das der Arbeitszeiteintrag gebucht werden soll. Die Angabe ist optional. Nur beim command "stop" wird dieser Parameter verarbeitet, bei allen anderen commands wird er ignoriert. Die projectid erhalten Sie über den API-Aufruf projects (siehe hier). Die Aktion projects brauchen Sie nur einmalig aufrufen. Die zurückgegebenen projectid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion projects nochmal aufrufen zu müssen, da sich die projectid nie ändert.
serviceid (optional)	Die ID der Kategorie, auf die der Arbeitszeiteintrag gebucht werden soll. Die Angabe ist optional. Nur beim command "stop" wird dieser Parameter verarbeitet, bei allen anderen commands wird er ignoriert. Die serviceid erhalten Sie über den API-Aufruf services (siehe hier). Die Aktion services brauchen Sie nur einmalig aufrufen. Die zurückgegebenen serviceid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion services nochmal aufrufen zu müssen, da sich die serviceid nie ändert.

Rückgabe-Daten

Im Response wird einer der folgenden Ergebniswerte zurückgegeben (beachten Sie auch die Besonderheit bei der Abfrage von status weiter unten):

Rückgabe-Daten bei status

Bei Übergabe des Kommandos status werden neben dem Ergebniswert noch weitere Informationen zum Status der Stempeluhr zurückgegeben. Die Daten werden im CSV-Format und UTF-8 codiert zurückgegeben. Die CSV-Datei beinhaltet keine Spaltenüberschriften, sondern besteht aus nur einer Zeile mit den Nutzdaten. Die Daten werden mit einem Semikolon separiert.

Beispiel:

Folgende Zeile wird zurückgegeben, wenn die Stempeluhr am 17.6.2019 um 14:10:45 Uhr gestartet wurde und um 14:15:01 Uhr pausiert wurde:

Aktion timeimportbyevents

Mit dieser Aktion können die Arbeitszeiteinträge von Stempeluhr-Terminals von Drittanbietern nach Timebutler importiert werden. Das Stempeluhr-Terminal kann die aufgezeichneten Stempeluhr-Ereignisse (Start, Pause, Stop) an Timebutler übermitteln und Timebutler wandelt diese Ereignisse in Arbeitszeiteinträge um.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/timeimportbyevents

Request-Parameter

Folgende zwei Parameter müssen übergeben werden:

Parametername	Typ	Wert
useridentification	HTTP Parameter	Um die Zeiteinträge zu den Mitarbeitern zuordnen zu können, muss bei dem Import der Daten entweder die Email-Adresse des Mitarbeiters oder die Mitarbeiternummer übergeben werden. Mit diesem Parameter wird festgelegt, ob in den importierten Daten die Email-Adresse oder die Mitarbeiternummer angegeben ist, wie folgt: Parameterwert email oder Parameter nicht angegeben: in den Import-Daten ist die Email-Adresse angegeben. Parameterwert employeenumber: in den Import-Daten ist die Mitarbeiternummer angegeben.
csvdatafile	File	Datei mit den zu importierenden Daten im CSV-Format. Details zum Aufbau der Daten siehe weiter unten.

Aufbau der CSV-Datei

In der CSV-Datei werden die Daten mit den Stempeluhr-Ereignissen übergeben. Je Zeile in der CSV-Datei wird ein Ereignis für einen Mitarbeiter übergeben. Die CSV darf keine Kopfzeilen beinhalten, es werden also alle Zeilen ab der ersten Zeile verarbeitet und importiert. Dass Trennzeichen der Daten in einer Zeile der CSV-Datei ist das Semikolon (;).

In jeder Zeile der CSV-Datei müssen folgende Daten in den Spalten übergeben werden:

Spalte / Wert	Beschreibung	Format / Beispiele
Erste Spalte Email-Adresse des Mitarbeiters oder Mitarbeiternummer	Bei den Request-Parametern kann im Parameter "useridentification" (siehe oben) angegeben werden, ob in der CSV-Datei die Email-Adresse des Mitarbeiters oder die Mitarbeiternummer angegeben ist. Entsprechend der Einstellung im Request Parameter muss in der CSV-Datei in dieser Spalte immer entweder die Email-Adresse des Mitarbeiters stehen oder immer die Mitarbeiternummer.	Email oder Mitarbeiternummer Beispiele: sarah@example.com MA0209
Zweite Spalte Zeitstempel	Datum und Uhrzeit, an dem das Ereignis aufgetreten ist (minutengenau).	jjjj-mm-ttThh:mm Das T bleibt unverändert, die anderen Buchstaben werden ersetzt: jjjj=Jahr mm=Monat 01-12 tt=Tag 01-31 hh=Stunde 00-23 mm=Minuten 00-59 Beispiele: 2024-03-31T17:58 (= 31. März 2024, 17:58 Uhr) 2024-12-02T07:08 (= 2. Dezember 2024, 7:08 Uhr)
Dritte Spalte Einer der Ereignistypen START STOP PAUSE RESUME	Mit dem Ereignistyp wird festgelegt, welches Ereignis zu dem übergebenen Zeitpunkt stattgefunden hat: START Stempeluhr wurde gestartet / Aufzeichnung gestartet STOP Stempeluhr wurde gestoppt / Aufzeichnung beendet PAUSE Stempeluhr wurde auf Pause gesetzt, Aufzeichnung der Pause wurde gestartet RESUME Pause an der Stempeluhr wurde beendet, Aufzeichnung der Arbeitszeit wurde fortgesetzt	Einer der 4 angegebenen Ereignis-Typen. Beispiele: START PAUSE
Vierte Spalte (optional) Die ID des Projekts, auf das der Arbeitszeiteintrag gebucht werden soll.	Die Angabe ist optional. Nur beim Ereignistyp STOP wird dieser Parameter verarbeitet, bei allen anderen Ereignistypen wird er ignoriert. Die ID des Projekts erhalten Sie über den API-Aufruf projects (siehe hier). Die Aktion projects brauchen Sie nur einmalig aufrufen. Die zurückgegebenen projectid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion projects nochmal aufrufen zu müssen, da sich die projectid nie ändert.	Beispiele: 4711 32977
Fünfte Spalte (optional) Die ID der Kategorie, auf die der Arbeitszeiteintrag gebucht werden soll.	Die Angabe ist optional. Nur beim Ereignistyp STOP wird dieser Parameter verarbeitet, bei allen anderen Ereignistypen wird er ignoriert. Die ID der Kategorie erhalten Sie über den API-Aufruf services (siehe hier). Die Aktion services brauchen Sie nur einmalig aufrufen. Die zurückgegebenen projectid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion services nochmal aufrufen zu müssen, da sich die serviceid nie ändert.	Beispiele: 4711 32977

Bedingungen an die CSV-Datei

• Je Zeile darf nur ein Ereignis übergeben werden
• Keine Kopfzeilen, alle Zeilen beinhalten nur Daten, keine Überschriftenzeile
• Spalteninhalte zwischen den Semikolons dürfen nicht in Hochkommata eingeschlossen werden (bzw. die Hochkommata werden wie übergeben eingelesen und verarbeitet)
• Die Ereignisse müssen in der richtigen zeitlichen Reihenfolge eingetragen sein, beginnend bei ältesten Ereignis zum neuesten Ereignis.
• Für einen Mitarbeiter muss das START-Ereignis der erste Eintrag sein, danach können PAUSE/RESUME folgen, schließlich muss STOP folgen. Es können mehrere dieser abgeschlossenen Ereigbnisabfolgen in einer Datei beinhaltet sein.
• Die Zeilen eines Mitarbeiters müssen nicht untereinander stehen, sondern es können Ereignisse verschiedener Mitarbeiter untereinander aufgelistet werden.
• Wenn eine Ereignisabfolge in der CSV-Datei nicht mit STOP endet, dann werden die Daten dieser Ereignisabfolge nicht importiert (z.B. Start um 9:45 Uhr, Pause um 12:03, danach keine weiteren Einträge in der CSV).
• In einer Ereignisabfolge dürfen START und STOP nicht weiter als 2 Kalendertage auseinanderliegen.
• Die CSV-Datei darf maximal 9216000 Bytes groß sein.

CSV-Datei Beispiel

Ein Arbeitszeiteintrag von 9:43 Uhr - 17:33 Uhr mit Pause zwischen 11:45 Uhr und 12:17 Uhr, gebucht auf Projekt ID 17 und Service ID 733, für einen Mitarbeiter:

Zwei Arbeitszeiteinträge für zwei Mitarbeiter, in zeitlich korrekter Abfolge, Zeilen jedoch nicht nach Mitarbeiter sortiert (da nicht notwendig). Es werden zwei Zeiteinträge generiert:

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Wenn kein Fehler aufgetreten ist und alle Zeilen korrekt verarbeitet werden konnten, dann wird lediglich ein OK zurückgegeben.

Wenn mindestens ein Fehler aufgetreten ist, dann wird für jede Zeile der CSV-Datei, die zu einem Fehler geführt hat, eine Rückmeldung wie folgt zurückgegeben: line #nn: Fehlercode

Beispiel: line #144: TIMESTAMP_INVALID

Aktion personnelfiles

Mit dieser Aktion werden die Daten aus der digitalen Personalakte eines oder aller Nutzer zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/personnelfiles

Request-Parameter

Einer der folgende Parameter kann als HTTP Post Parameter übergeben werden, um die Daten von nur einem Mitarbeiter abzufragen. Wenn kein Parameter übergeben wird, werden alle Daten aller Mitarbeiter zurückgegeben.

Parametername	Pflichtangabe	Wert
email	Nein	Die Email-Adresse des Nutzerkontos, für das die Daten zurückgeliefert werden sollen.
employeenumber	Nein	Die Mitarbeiter-Nummer des Mitarbeiters, für den die Daten zurückgeliefert werden sollen.
userid	Nein	Die eindeutige userid des Nutzerkontos, für das die Daten zurückgeliefert werden sollen. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Daten aus der Personalakte der Nutzer. Die Daten sind mit einem Semikolon separiert.

Aktion salaries

Mit dieser Aktion werden die Gehaltsdaten eines oder aller Nutzer zurückgeliefert.

Abfrage-URL:

https://personalmanagement.ulb.tu-darmstadt.de/api/v1/salaries

Request-Parameter

Einer der folgende Parameter kann als HTTP Post Parameter übergeben werden, um die Daten von nur einem Mitarbeiter abzufragen. Wenn kein Parameter übergeben wird, werden alle Daten aller Mitarbeiter zurückgegeben.

Parametername	Pflichtangabe	Wert
email	Nein	Die Email-Adresse des Nutzerkontos, für das die Daten zurückgeliefert werden sollen.
employeenumber	Nein	Die Mitarbeiter-Nummer des Mitarbeiters, für den die Daten zurückgeliefert werden sollen.
userid	Nein	Die eindeutige userid des Nutzerkontos, für das die Daten zurückgeliefert werden sollen. Die Liste aller userid erhalten Sie über den API-Aufruf users (siehe hier). Die Aktion users brauchen Sie nur einmalig aufrufen. Die zurückgegebenen userid-Werte können Sie auf Ihrem System speichern und wiederverwenden, ohne die Aktion users nochmal aufrufen zu müssen, da sich die userid nie ändert.

Rückgabe-Daten

Im Response werden die Daten im CSV-Format und UTF-8 codiert zurückgegeben. Die erste Zeile der CSV-Datei beinhaltet die Spaltenüberschriften. Darauf folgen zeilenweise die Gehaltsdaten. Wenn für einen Mitarbeiter mehrere Gehaltsdaten hinterlegt sind (beispielsweise Gehalt, variable Vergütung und Bonuszahlungen), werden mehrere Zeilen für den gleichen Mitarbeiter zurückgegeben. Die Daten sind mit einem Semikolon separiert. Sind keine Einträge vorhanden, wird nur die erste Zeile mit den Spaltenüberschriften zurückgegeben.

Code Beispiele

Das XXXXXXX unten im Quellcode unten ersetzen Sie mit Ihrem API Token.

Curl

curl -X POST 'https://timebutler.de/api/v1/absences' -d 'auth=XXXXXXX'

Python

import requests
url = 'https://timebutler.de/api/v1/absences'
params = {'auth': 'XXXXXXX'}
response = requests.post(url, params=params)
response.text

Java

public String requestTimebutlerApi()
{
  String postData = "auth=" + URLEncoder.encode("XXXXXXX", "UTF-8"); // java.net.URLEncoder
  String targetUrl = "https://timebutler.de/api/v1/absences";
  
  String responseTxt = "";
  
  URL url = new URL(targetUrl); // java.net.URL
  HttpURLConnection connection = (HttpURLConnection)url.openConnection(); // java.net.HttpURLConnection
  
  connection.setRequestMethod("POST");
  connection.setUseCaches(false);
  connection.setDoOutput(true);
  connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
  connection.setRequestProperty("Content-Length", String.valueOf(postData.length()));
  connection.getOutputStream().write(postData.getBytes("UTF-8"));
  
  BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream(), "UTF-8")); // java.io.BufferedReader
  
  String line;
  while ((line = in.readLine()) != null) {
    responseTxt += line + "\n";
  }
  
  if (connection != null) {
    connection.disconnect();
  }
  
  return responseTxt;
  }

Powershell

$url = "https://timebutler.de/api/v1/absences"
$body = @{
  auth = "XXXXXXX"
}

Invoke-RestMethod -Method 'Post' -Uri $url -Body $body -ContentType "application/x-www-form-urlencoded"

# If you want the output to be written into a file just add the following parameter to the last line above: -OutFile output.csv


VBA (Excel, ...)

Sub requestTimebutlerApi()
 Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
 URL = "https://timebutler.de/api/v1/absences"
 objHTTP.Open "POST", URL, False
 objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
 objHTTP.Send ("auth=[XXXXXXX]")

 replyTXT = objHTTP.responseText

 If objHTTP.Status = "200" Then 'success
  MsgBox replyTXT
 Else
  MsgBox objHTTP
 End If
End Sub

Zum Seitenanfang