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. Alle Aufrufe müssen immer über https erfolgen. Aufrufe über http werden mit einer Fehlermeldung zurückgewiesen. Die URL für alle Abfragen lautet:

https://timebutler.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://timebutler.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://timebutler.de/api/v1/absences
users	Nutzerdaten auslesen Liefert eine Liste aller Nutzer zurück. https://timebutler.de/api/v1/users
holidayentitlement	Urlaubsanspruchsdaten auslesen Liefert eine Liste aller Urlaubsanspruch-Werte aller Nutzer für ein bestimmtes Jahr zurück. https://timebutler.de/api/v1/holidayentitlement
workdays	Arbeitstage der Nutzer auslesen Liefert eine Liste der Arbeitstage der Nutzer zurück. https://timebutler.de/api/v1/workdays
holidaysets	Feiertagsregelungen auslesen Liefert eine Liste der Feiertagsregelungen zurück. https://timebutler.de/api/v1/holidaysets
worktime	Arbeitszeiteinträge der Nutzer auslesen Liefert eine Liste der Arbeitszeiteinträge der Nutzer zurück. https://timebutler.de/api/v1/worktime
projects	Liste der Projekte auslesen Liefert eine Liste aller konfigurierten Projekte (Zeiterfassung) zurück. https://timebutler.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://timebutler.de/api/v1/projectsimport
services	Liste der Kategorien auslesen Liefert eine Liste aller konfigurierten Kategorien (Zeiterfassung) zurück. https://timebutler.de/api/v1/services
timeclock	Virtuelle Stempeluhr steuern Stellt Kommandos zum Starten, Pausieren und Stoppen der virtuellen Stempeluhr bereit. https://timebutler.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://timebutler.de/api/v1/timeimportbyevents
personnelfiles	Personalakte abfragen Zur Abfrage von Daten aus der digitalen Personalakte. https://timebutler.de/api/v1/personnelfiles
salaries	Gehaltsdaten abfragen Zur Abfrage von Gehaltsdaten der Mitarbeiter. https://timebutler.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://timebutler.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 users

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

Abfrage-URL:

https://timebutler.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://timebutler.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 workdays

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

Abfrage-URL:

https://timebutler.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 holidaysets

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

Abfrage-URL:

https://timebutler.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://timebutler.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://timebutler.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://timebutler.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 die ID ignoriert, falls sie dennoch übergeben wird). 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 3072000 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://timebutler.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 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://timebutler.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). businesstripstart Einen Dienstgang starten (nur möglich, wenn die Stempeluhr gestartet ist). businesstripstop Einen Dienstgang stoppen (nur möglich, wenn der Dienstgang zuvor gestartet wurde).
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://timebutler.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
Sechste Spalte (optional) Die Bemerkungen zu dem Arbeitszeiteintrag (einzeilig, keine Zeilenumbrüche).	Die Angabe ist optional. Nur beim Ereignistyp STOP wird dieser Parameter verarbeitet, bei allen anderen Ereignistypen wird er ignoriert. Wenn Bemerkungen angegeben sind, dann müssen diese in einer Zeile ohne Zeilenumbruch und ohne Sonderzeichen eingetragen sein. Ein Semikolon kann nicht verwendet werden, da das Semikolon als Trennzeichen für die CSV-Datei dient.	Beispiel: Wie besprochen habe ich an dem Tag später gestartet.

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 3072000 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://timebutler.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://timebutler.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;
}

Rust

use reqwest;

fn main() {
  request_timebutler_api()
}

fn request_timebutler_api() {

  let url = "https://timebutler.de/api/v1/absences";
  let params = [("auth", "XXXXXXX")];
  let client = reqwest::blocking::Client::new();
  let resp = match client
    .post(url)
    .form(&params)
    .send() {
      Ok(resp) => resp.text().unwrap(),
      Err(err) => panic!("Error: {}", err)
    };
}


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


Google Apps Script

function requestAbsences() {

  var apiUrl = "https://timebutler.de/api/v1/absences";
  var authtoken = "XXXXXXX";

  var formData = {
    'auth': authtoken
  };

  var options = {
    'method' : 'post',
    'payload' : formData
  };

  try {
    var response = UrlFetchApp.fetch(apiUrl, options);
    var responseData = response.getContentText();
  }
  catch (e) {
    Logger.log(e);
  }

};

Powerquery

let
  ApiKey = "XXXXXXX",
  baseUrl = "https://timebutler.de/api/v1/absences",
  headers = [#"Content-Type" = "application/x-www-form-urlencoded"],
  postData = "auth=" & ApiKey,
  response = Web.Contents(
    baseUrl,
      [
        Headers = headers,
        Content = Text.ToBinary(postData)
      ]
    ),
  csvResponse = Csv.Document(response, [Delimiter=";"]),
  #"PromoteHeader" = Table.PromoteHeaders(csvResponse, [PromoteAllScalars=true])
in
  #"PromoteHeader"


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