Zeiterfassung & Lohnbuchhaltung¶
Zeiterfassung – Abruf der Gleitzeitstände¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.x / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | ja |
| Endpunkt-Pfad | /integrations/tokenapi/v2/aaa-bbb-ccc/time-tracking |
Erfahren Sie hier, wie Gleitzeitstände automatisiert oder manuell abgerufen werden kann. Im Abschnitt Konfiguration haben Sie sogenannte „Schichtgruppen-Token“ als Zugänge zu den Daten in Planerio erstellt, diese werden nun benötigt.
️ Bitte beachten Sie, dass dieser Endpunkt erst durch Ihren Planerio Account Manager aktiviert werden muss (Stichwort TIMESHEET_API_ARCHIVE_START_MONTH_YEAR). Nach Aktivierung kann der Abruf am nachfolgenden Tag genutzt werden.
Die URL zum Datenabruf lautet:
https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/time-tracking
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 &.
| Parameter | Beschreibung |
|---|---|
| startMonth=2022-01 | Dieser Parameter definiert den Beginn des Zeitraums, für den der Gleitzeitstand abgerufen werden sollen. Das Datum muss dabei im Format YYYY-MM, also z.B. 2020-12 für Dezember 2020, angegeben werden. Das Jahr muss im Bereich 2000-2099 liegen. |
| endMonth=2022-01 | Dieser Parameter definiert das Ende des Zeitraums, für den der Gleitzeitstand abgerufen werden sollen. |
Folgende Daten sind enthalten (jeweils eine Zeile pro Mitarbeiter und Jahr/Monat):
| Feldname | Beschreibung |
|---|---|
| flexitime | Gleitzeitstand |
| unadjustedFlexitime | Gleitzeitstand vor manueller Korrektur |
| targetHours | Sollstunden |
| netHours | Nettostunden/Iststunden |
| year | Jahr |
| month | Monat |
| personnelNumber | Personalnummer des Mitarbeiters |
| employee_uuid | Planerio-systemweit eindeutige ID des Mitarbeiters |
️Bei nachträglichen Korrekturen stehen die aktualisierten Werte in der Regel erst am Tag nach der Korrektur zur Verfügung!
ℹ️ Falls dieser Endpunkt nach 20+ Sekunden den Fehler 503 zurückliefert, verringern Sie bitte die Anzahl Monate, die abgerufen werden, oder die Anzahl der Mitarbeiter. Die Anzahl der Mitarbeiter kann über separate Schichtgruppen-Token gesteuert werden. Im Extremfall kann es nötig sein, einen separate Token für jede Schichtgruppe zu verwenden. Für 2025 ist damit zu rechnen, dass diese Limitierung entfernt werden kann.
Zeiterfassung – Erstellen/Importieren von Zeitstempeln¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.x / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | ja |
| Endpunkt-Pfad | /integrations/tokenapi/v2/aaa-bbb-ccc/timestampEvent |
Über diesen Endpunkt können Sie Zeitstempel (Kommen/Gehen) in Planerio erstellen. Die Zeitstempel verhalten sich so, als wenn sie über Zeiterfassungs-Hardware oder die mobile Planerio-App erstellt worden wären. Die URL des Endpunktes lautet:
https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/timestampEvent
Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen (vgl. Abschnitt Konfiguration).
Zeitstempel können nur für Mitarbeiter erstellt 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.
Folgende Parameter stehen zur Verfügung:
| Feldname | Beschreibung |
|---|---|
| personnel_number | Personalnummer zur Identifikation des Mitarbeiters. Falls die Personalnummer innerhalb der verknüpften Schichtgruppe(n) nicht eindeutig ist, wird ein entsprechender Fehler zurückgegeben. |
| in_out | Entweder „in“ (Kommen / Einstempeln) oder „out“ (Gehen / Ausstempeln). |
| date_time | Datum/Uhrzeit im Format YYYY-MM-DD HH:MM:SS Folgende Einschränkungen gelten: - Kann nicht weiter als 5 Minuten in der Zukunft liegen - Kann nicht vor dem 1. Januar des letzten Jahres liegen - Kann nicht vor dem ersten Arbeitstag des Mitarbeiters liegen |
| comment | (Optional) Kommentar, bis zu 4000 Zeichen. |
Die Felder sind als POST-Request zu übermitteln. Hier ein Beispiel mit curl:
curl -v \
--data-urlencode 'personnel_number=001234' \
--data-urlencode 'in_out=out' \
--data-urlencode 'date_time=2020-23-05 19:13:37' \
-H 'X-Planerio-Api-Gateway-Auth: SESSIONTOKEN' \
'https://HOST/integrations/tokenapi/v2/AAA-BBB-CCC/timestampEvent'
Falls der Stempel erfolgreich gespeichert wurde (oder ein identischer Stempel bereits existiert), wird der HTTP-Status-Code 204 und eine leere Antwort zurückgegeben.
Zeiterfassung – Abrufen von Zeitstempeln¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.x / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | ja |
| Endpunkt-Pfad | /integrations/tokenapi/v1/aaa-bbb-ccc/timestampEvents |
Über diesen Endpunkt können Sie „rohe“ Zeitstempel (Kommen/Gehen) aus Planerio abrufen. Die URL des Endpunktes lautet:
https://<host>/integrations/tokenapi/v1/aaa-bbb-ccc/timestampEvents
Anstelle von aaa-bbb-ccc ist das entsprechende Schichtgruppen-Token einzusetzen (vgl. Abschnitt Konfiguration). Folgende Parameter stehen zur Verfügung. Der erste Parameter muss dabei mit einem ? eingeleitet werden, alle folgenden mit einem &.
| Parameter | Beschreibung |
|---|---|
| startDate=2023-01-01 | Dieser Parameter definiert den Beginn des Zeitraums, für den Zeitstempel abgerufen werden sollen. Das Datum muss dabei im Format YYYY-MM-DD, also z.B. 2020-12-31 für den 31. Dezember 2020, angegeben werden. Das Jahr muss im Bereich 2000-2099 liegen. |
| endDate=2023-01-31 | Dieser Parameter definiert das Ende des Zeitraums, für den Zeitstempel abgerufen werden sollen. |
| includeDeleted=1 | (optional) Gelöschte Zeitstempel werden standardmäßig nicht zurückgegeben. Falls Sie diese benötigen, können Sie sie über den angegebenen Parameter in das Ergebnis einschließen. |
| updatedAfter=2023-02-01 | (optional) Mit diesem Parameter können die Zeitstempel auf solche eingeschränkt werden, die sich nach einem Stichtag geändert haben. Dies ist nützlich für Differenzbetrachtungen. Das Datum ist als YYYY-MM-DD zu formatieren. |
| withMetaData=1 | Aktiviert zusätzliche Felder in der Antwort (siehe unten). Hierdurch kann sich die Performance verschlechtern. |
Folgende Datenfelder werden pro Zeitstempel geliefert:
| Feldname | Beschreibung |
|---|---|
| timestamp_uuid | Eindeutige ID des Stempel-Ereignisses |
| date_time | Datum und Uhrzeit im Format YYYY-MM-DD HH:MM:SS |
| in_out | Entweder „in“ (Kommen / Einstempeln) oder „out“ (Gehen / Ausstempeln). |
| employee_personnel_number | Personalnummer des zugehörigen Mitarbeiters |
| employee_uuid | Planerio-systemweit eindeutige ID des Mitarbeiters |
| deleted_at | (nur wenn Parameter includeDeleted gesetzt) Falls Zeitstempel gelöscht, Zeitpunkt der Löschung im Format YYYY-MM-DD HH:MM:SS |
| date_time_original | Falls eine Korrektur des Zeitstempels stattgefunden hat, ist hier der unkorrigierte Wert im selben Format wie date_time enthalten. |
| employee_external_id | Falls der Mitarbeiter über einen Import (vgl. separate Doku „Schnittstelle_Mitarbeiterdatenimport“) angelegt wurde, ist hier die uniqueId zur Identifizierung des MA im externen System enthalten. |
| employee_cost_center | Kostenstelle des Mitarbeiters (sofern vorhanden) |
| employee_first_name employee_last_name |
(mit withMetaData=1) Vor-/Nachname des Mitarbeiters |
| request_reason | (mit withMetaData=1) Falls der Zeitstempel durch einen Antrag erstellt oder geändert wurde, ist hier der Freitext für den Antragsgrund enthalten. |
| approved_by_display_name | (mit withMetaData=1) Falls der Zeitstempel durch einen Antrag erstellt oder geändert wurde: Name des Mitarbeiters, der den Antrag freigegeben hat. |
Lohnbuchhaltung – Abruf von manuellen Zuschlägen¶
| Information | Wert |
|---|---|
| Verfügbar in Planerio-Versionen | 1.x / 2.0 |
| Verfügbar über Technisches Login | ja |
| Verfügbar über Browser | nein |
| Endpunkt-Pfad | /planerio/timetracking/payroll/api/external/token-api/aaa-bbb-ccc/manual-bonuses |
Über diesen Endpunkt können manuelle Zuschläge („Boni“) aus der vorbereitenden Lohnbuchhaltung abgerufen werden. Automatisch vergebene Boni sind hierüber nicht abrufbar.
️ Bitte beachten Sie, dass dieser Endpunkt erst nach Rücksprache mit Ihrem Planerio Account Manager verwendet werden sollte.
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/timetracking/payroll/api/external/token-api/aaa-bbb-ccc/manual-bonuses
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 &.
| Parameter | Beschreibung |
|---|---|
| year=2023 | Dieser Parameter definiert das Jahr des Zeitraums, für den Boni abgerufen werden sollen. |
| month=6 | Dieser Parameter definiert den Monat des Zeitraums. |
Folgende Daten sind in der Antwort enthalten (jeweils pro Bonus):
| Feldname | Datentyp | Beschreibung |
|---|---|---|
| unique_bonus_id | string | Eindeutige ID für diesen Zuschlag |
| employee_uuid | string | Planerio-systemweit eindeutige ID des Mitarbeiters |
| employee_personnel_number | string|null | Personalnummer des Mitarbeiters |
| employee_external_id | string|null | Falls der Mitarbeiter über einen Import (vgl. separate Doku „Schnittstelle_Mitarbeiterdatenimport“) angelegt wurde, ist hier die uniqueId zur Identifizierung des MA im externen System enthalten. |
| is_deleted | bool | Löschkennzeichen |
| updated_at | string | Änderungszeitstempel im Format YYYY-MM-DD HH:MM:SS |
| payroll_code | string | Lohnart |
| value | number | Numerischer Wert, z.B. Anzahl Stunden, Tage, Schichten oder Euro |
| unit | string | Einheit von Value, eins von: OTHER|HOURS|EURO|SHIFTS |
| wage_factor | number|null | Wert in Euro für Boni vom Typ „Euro pro Stunde/Schicht/Tag“ |
| start_date_time | string | Nur für Boni vom Wert-Typ „Zeitraum“ – Startzeit im Format YYYY-MM-DD HH:MM:SS |
| end_date_time | string | Nur für Boni vom Wert-Typ „Zeitraum“ – Endzeit im Format YYYY-MM-DD HH:MM:SS |
| payroll_bonus_reason | string | Kommentar des Nutzers welcher den Zuschlag beantragt hat |