Abwesenheiten¶

Abruf von Abwesenheitsperioden¶

Im Abschnitt Konfiguration haben Sie sogenannte „Schichtgruppen-Token“ als Zugänge zu den Daten in Planerio erstellt, diese werden nun benötigt. Die URL zum Datenabruf lautet:

https://<host>/planerio/absences/api/external/tokenapi/aaa-bbb-ccc/absencePeriods

Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen. Weiterhin ist es nötig, den Datenabruf wie folgt zu parametrisieren. Der erste Parameter muss dabei mit einem ? eingeleitet werden, alle folgenden mit einem &.

Folgende Parameter stehen optional zur Verfügung:

Folgende Daten sind enthalten (jeweils ein JSON-Objekt pro Abwesenheitsperiode):

Über diese Schnittstelle können Sie Abwesenheitsperioden aus Planerio abrufen. Perioden, die über den "Import von Abwesenheitsperioden" (siehe unten) angelegt wurden (d.h. extern verwaltet sind), werden nicht zurückgegeben.

Import von Abwesenheitsperioden¶

Über diesen Endpunkt können Sie Abwesenheitsperioden in Planerio anlegen. Die entsprechenden Abwesenheits-Typen müssen bereits in Planerio existieren. Importierte Abwesenheitsperioden können in Planerio nicht durch Nutzer und Admins genehmigt, bearbeitet oder gelöscht werden, d.h. sind nur sichtbar, aber in keiner Form änderbar.

Die URL des Endpunktes lautet:

https://<host>/integrations/tokenapi/v1/aaa-bbb-ccc/absencePeriod

Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen (vgl. Abschnitt Konfiguration).

Abwesenheiten können nur für Mitarbeiter erstellt/verändert/gelöscht werden, deren primäre Schichtgruppe mit dem verwendeten Schichtgruppen-Token verknüpft ist. So kann die Funktionalität ggf. auf bestimmte Schichtgruppen beschränkt werden.

Anlegen und Updaten (HTTP POST)¶

Folgende Parameter stehen zur Verfügung:

Die Felder sind als POST-Request zu übermitteln. Hier ein Beispiel mit curl:

curl -v \
  --data-urlencode 'unique_absence_id=A1182783912' \
  --data-urlencode 'absence_type_key=0400' \
  --data-urlencode 'employee_personnel_number=001234' \
  --data-urlencode 'date_from=2023-07-17' \
  --data-urlencode 'date_to=2023-07-17' \
  -H 'X-Planerio-Api-Gateway-Auth: SESSIONTOKEN' \
  'https://HOST/integrations/tokenapi/v1/AAA-BBB-CCC/absencePeriod'

Falls die Abwesenheit erfolgreich angelegt oder aktualisiert wurde, wird der HTTP-Status-Code 204 und eine leere Antwort zurückgegeben.

Löschen (HTTP DELETE)¶

Das Löschen einer Abwesenheitsperiode wird über ein HTTP-Request mit Methode DELETE realisiert. Folgende Parameter werden in der URL übergeben:

Vollständige URL: https://<host>/integrations/tokenapi/v1/aaa-bbb-ccc/absencePeriod/<unique_absence_id>

Falls die Abwesenheit erfolgreich gelöscht wurde oder bereits nicht mehr existierte, wird der HTTP-Status-Code 204 und eine leere Antwort zurückgegeben.

Beispiel-Aufruf mit curl:

curl -v -XDELETE \
  -H 'X-Planerio-Api-Gateway-Auth: SESSIONTOKEN' \
  'https://HOST/integrations/tokenapi/v1/AAA-BBB-CCC/absencePeriod/A1182783912'

Einmaliger Import¶

Während der primäre Anwendungsfall für die Schnittstelle der kontinuierliche Import von Abwesenheitsperioden aus einem Drittsystem ist, kann er auch für das einmalige Anlegen einer größeren Menge an Abwesenheiten in Planerio angewendet werden.

Dazu ist die POST-Anfrage (vgl. oben) wie folgt zu parametrisieren:

So importierte Perioden sind

• in Planerio bearbeitbar und verhalten sich auch sonst wie „normal“, also direkt aus Planerio, erstellte Abwesenheitsperioden.

• Nachträglich über die Schnittstelle nicht mehr aktualisierbar (mangels unique_absence_id).

Abruf des Urlaubsbudgets¶

Erfahren Sie hier, wie Urlaubsdaten automatisiert oder manuell abgerufen werden kann, um möglicherweise Urlaubsrückstellungen zu berechnen. Im Abschnitt Konfiguration haben Sie sogenannte „Schichtgruppen-Token“ als Zugänge zu den Daten in Planerio erstellt, diese werden nun benötigt. Die URL zum Datenabruf lautet:

https://<host>/integrations/tokenapi/v3/aaa-bbb-ccc/absences/vacationDays

️ Bitte beachten Sie, dass bei diesem Endpunkt unbedingt „v3“ (siehe URL) eingesetzt werden muss. Die älteren Versionen werden nicht mehr unterstützt.

Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen. Weiterhin ist es möglich, den Datenabruf wie folgt zu parametrisieren. Der erste Parameter muss dabei mit einem ? eingeleitet werden, alle folgenden mit einem &.

Folgende Daten sind pro Zeile/Datensatz enthalten:

ℹ️ Dieser Endpunkt wird in 2026/27 im Rahmen der Einführung von mehreren Budgets ersetzt.