Einrichtung der Personio Anwesenheits-API

Dieser Artikel ist ein Leitfaden zur Nutzung der Personio Anwesenheits-API, die in Verbindung mit Integrationen und externen Tools genutzt werden kann. Die API bietet Ihnen die Möglichkeit (mit Hilfe eines IT Experten), in Personio hinterlegte Anwesenheitszeiten Ihrer Mitarbeiter in Form von Rohdaten sowohl abzurufen als auch die Anwesenheitszeiten in Personio einzuspielen.

Bitte beachten Sie, dass Ihnen die Nutzung der Anwesenheits-API lediglich ab dem Personio Enterprise Paket zur Verfügung steht. Für einen Paketwechsel und weitere Informationen kontaktieren Sie uns gerne unter upgrade@personio.de.

 

Bitte beachten Sie, dass Sie für die Anbindung der Anwesenheits-API einen IT Experten hinzuziehen sollten. Die technische Dokumentation unserer API mit allen Endpunkten sowie technische Tutorials finden Sie unter https://developer.personio.de/.

 

Authentifizierung und Nutzung

Sowohl der GET- als auch der POST-Endpunkt sind gesichert und nur durch Authentifizierung über einen Sicherheits-Token zugänglich. Weitere Informationen dazu finden Sie hier.

 

Im Folgenden beschreiben wir die Unterschiede zwischen den beiden Endpuntken GET und POST:

  • GET / company / attendances
  • POST / company / attendances

 

1. Abrufen von Anwesenheitsinformation Ihrer Mitarbeiter (GET)

Endpunkt /company/attendances
Methode GET
Beschreibung

Von diesem Endpunkt aus werden die Anwesenheiten Ihrer Mitarbeiter abgefragt.

Durch Seitenumbrüche haben Sie die Möglichkeit, sich die Anwesenheitsinformationen aufgegliedert auf mehreren Seiten anzeigen zu lassen, um eine bessere Übersicht zu erhalten. Zudem können Sie die abgerufenen Anwesenheitsinformationen nach einem für Sie relevanten Zeitraum bzw. bestimmten Mitarbeitern filtern und/oder inaktive Mitarbeiter in Ihre Suche einbeziehen.

 

Filter

Im Folgenden finden Sie eine Auflistung von Filtern, welche Sie für das Abrufen der Anwesenheitsinformationen verwenden können: 

Filter Typ Format Erforderlich Standard Beschreibung
start_date string YYYY-mm-dd ja   Erster Tag des abzufragenden Zeitraums. Der erste Tag selbst wird bei den Ergebnissen ebenfalls berücksichtigt.
end_date string YYYY-mm-dd ja   Letzter Tag des abzufragenden Zeitraums. Der letzte Tag selbst wird bei den Ergebnissen ebenfalls berücksichtigt. Wenn der erste und letzte Tag identisch sind, werden nur die Anwesenheiten dieses Tages ausgegeben.
employees array [int, ...] nein  

Um die Anwesenheits-informationen nach gewissen Mitarbeitern zu filtern, verwenden Sie die Personio-IDs Ihrer Mitarbeiter. 

Falls keine Filter gesetzt sind, werden Anwesenheiten von allen Mitarbeitern abgerufen.

limit int   nein 200

Limitieren Sie die ausgegebenen Datensätze über den Limit-Befehl.

Beispiel: Sie möchten die Anwesenheitsdaten auf eine Anzahl von 200 begrenzen. Setzen Sie das Limit auf "200".

Ihnen werden nun lediglich 200 Zeilen ausgegeben.

offset int   nein 0

Verkleinern Sie die Datensätze, welche über die API ausgegeben werden, mit dem Offset-Befehl.

Beispiel: Sie möchten die Anwesenheitsdaten erst ab der Zeile 300 abfragen. Setzen Sie den Offset auf "300".

Bei der Abfrage werden Ihnen nun die Zeilen 300 bis zu ihrem Limit (siehe oben) ausgegeben.

Eine limitierte Abfrage ist v.a. aus Speichergründen sowie zur Reduzierung von Ladezeiten von Vorteil.

 

Parameter zum Abruf der Anwesenheitszeiträume

Sehen Sie hier die unterschiedlichen Attribute und Typen, welche für den Abruf der Anwesenheitszeiträume relevant sind.

Attribut Typ Format Beschreibung
date string YYYY-mm-dd Anwesenheitstag
start_time string hh:mm Startzeit
end_time string hh:mm Endzeit
break int   Anzahl der Minuten der Pause
comment string   Beschreibung oder Kommentar bzgl. der Anwesenheit
is_holiday boolean [richtig/falsch] Liegt die Anwesenheit auf einem Feiertag oder nicht? 
is_on_time_off boolean [richtig/falsch] Liegt die Anwesenheit auf einem Tag, für welchen eine "echte" Abwesenheit (Absence is time off) hinterlegt ist? Falls ja, berechnet Personio für die Stunden der Anwesenheit Überstunden. 
employee int   Mitarbeiter ID 

 

2. Hinzufügen von Anwesenheitsinformation Ihrer Mitarbeiter (POST)

Endpunkt /company/attendances
Methode POST
Beschreibung Von diesem Endpunkt aus werden Anwesenheiten Ihrer Mitarbeiter hinzugefügt. Es ist möglich, Anwesenheiten für einen oder mehrere Mitarbeiter gleichzeitig hinzuzufügen. Das gesendete Datenpaket sollte eine Liste der Anwesenheitszeiträume in Form eines Arrays sein.

 

Die Filter für das Hinzufügen der Anwesenheitsinformationen sind identisch zu den Filtern für das Abrufen der Anwesenheitsinformationen. Diese finden Sie weiter oben.

 

Parameter zum Hinzufügen der Anwesenheitszeiträume

Sehen Sie hier die unterschiedlichen Attribute und Typen, welche für das Hinzufügen der Anwesenheitszeiträume relevant sind.

Attribut Typ Format Beschreibung
date string YYYY-mm-dd Anwesenheitstag
start_time string hh:mm Startzeit
end_time string hh:mm Endzeit
break int   Anzahl der Minuten der Pause
comment string   Beschreibung oder Kommentar bzgl. der Anwesenheit
employee int   Mitarbeiter ID

 

Validierung

Die folgenden Fälle führen zu einem Validierungsfehler und die Daten können nicht in Personio gespeichert werden:

  • Anwesenheitszeitraum start_time und end_time überschneiden sich mit einem anderen Anwesenheitszeitraum, der bereits in Personio für den selben Tag hinterlegt ist
  • Keine Mitarbeiter für den eingestellten Filter gefunden
  • Unvollständiges Datenpaket (start-time oder end_time fehlen) 

 

Haben Sie Fragen? Anfrage einreichen

0 Kommentare

Zu diesem Beitrag können keine Kommentare hinterlassen werden.