Zeiterfassung & Lohnbuchhaltung¶

Zeiterfassung – Abruf täglicher Zeitkontenwerte¶

Über diesen Endpunkt können Sie Sollzeit, Nettozeit, Pausenzeit und Gleitzeitwerte für jeden Tag eines abgeschlossenen Monats abrufen. Die Antwort ist für den einfachen Import in ein BI-System strukturiert.

Für den Datenabruf benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token. Berücksichtigt werden nur Mitarbeiter, deren primäre Schichtgruppe mit diesem Token verknüpft ist. Deaktivierte oder gelöschte Mitarbeiter sowie Mitarbeiter mit deaktivierter Zeiterfassung sind nicht enthalten.

Die URL zum Datenabruf lautet:

https://<host>/planerio/timetracking/timesheet/api/external/v1/aaa-bbb-ccc/daily-balances?year=2025&month=1

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token. Die Query-Parameter year und month sind erforderlich.

Folgende Daten sind in der Antwort enthalten. Für einen abgeschlossenen Monat wird pro Mitarbeiter und Kalendertag eine Zeile zurückgegeben:

Beispiel-Antwort:

[
  {
    "employee_uuid": "7e6e30ea-4890-4cab-b52e-e40e1a2ce58d",
    "employee_external_id": "ext-4711",
    "employee_personnel_number": "0123",
    "employee_name": "Erika Mustermann",
    "status": "month_closed",
    "year": 2025,
    "month": 1,
    "day": 2,
    "break_minutes": 30,
    "net_minutes": 450,
    "target_minutes": 420,
    "flexitime_daily_minutes_before_bonuses": 30,
    "flexitime_accumulated_minutes": 1230,
    "flexitime_change_minutes": 30
  }
]

Liegen für einen berücksichtigten Mitarbeiter keine abgeschlossenen Monatsdaten vor, enthält die Antwort für diesen Mitarbeiter genau eine Zeile mit status: "unavailable". Die Datums- und Zeitwertfelder fehlen in diesem Fall.

Ein fehlender Pflichtparameter, ein Jahr vor 2020, ein ungültiger Monat oder ein zukünftiger Monat führt zum HTTP-Status-Code 400.

Zeiterfassung – Abruf monatlicher Zeitkontenwerte¶

Über diesen Endpunkt können Sollzeit, Nettozeit und Gleitzeitwerte für einen Monat abgerufen werden. Die Antwort enthält genau eine Zeile pro Mitarbeiter. Neben abgeschlossenen Monaten können Sie auch einen offenen Monat abfragen, sofern dafür bereits berechnete Zeitkontenwerte vorliegen.

Berücksichtigt werden nur Mitarbeiter, deren primäre Schichtgruppe mit dem verwendeten Schichtgruppen-Token verknüpft ist. Deaktivierte oder gelöschte Mitarbeiter sowie Mitarbeiter mit deaktivierter Zeiterfassung sind nicht enthalten.

Die URL zum Datenabruf lautet:

https://<host>/planerio/timetracking/timesheet/api/external/v1/aaa-bbb-ccc/monthly-balances?year=2025&month=1

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token. Die Query-Parameter year und month sind erforderlich.

Folgende Daten sind in der Antwort enthalten:

Beispiel-Antwort:

[
  {
    "employee_uuid": "7e6e30ea-4890-4cab-b52e-e40e1a2ce58d",
    "employee_external_id": "ext-4711",
    "employee_personnel_number": "0123",
    "employee_name": "Erika Mustermann",
    "status": "month_closed",
    "year": 2025,
    "month": 1,
    "day": 31,
    "net_minutes": 9840,
    "target_minutes": 9600,
    "flexitime_minutes": 700,
    "flexitime_unadjusted_minutes": 760,
    "flexitime_minutes_month_start": 460
  }
]

month_closed kennzeichnet einen abgeschlossenen Monat. month_open kennzeichnet einen offenen Monat und enthält den zuletzt berechneten Stand. Liegen für einen berücksichtigten Mitarbeiter weder abgeschlossene noch berechnete offene Monatsdaten vor, wird status: "unavailable" zurückgegeben; die Datums- und Zeitwertfelder sind dann null.

Ein fehlender Pflichtparameter, ein Jahr vor 2020, ein ungültiger Monat oder ein zukünftiger Monat führt zum HTTP-Status-Code 400.

Seitennummerierung für tägliche und monatliche Zeitkontenwerte¶

Die Endpunkte daily-balances und monthly-balances liefern pro Seite die Daten von höchstens 250 Mitarbeitern. Die Seitennummerierung bezieht sich auf Mitarbeiter, nicht auf einzelne Tages- oder Monatszeilen. Daher enthält eine Antwort immer alle Zeilen eines Mitarbeiters.

• Sind höchstens 250 berechtigte Mitarbeiter mit dem Schichtgruppen-Token verknüpft, kann der Parameter page entfallen.
• Sind mehr als 250 berechtigte Mitarbeiter verknüpft, ist page erforderlich. Ein Aufruf ohne diesen Parameter wird mit dem HTTP-Status-Code 422 abgelehnt; die Antwort weist darauf hin, dass page angegeben werden muss.
• page=1 liefert die ersten 250 Mitarbeiter, page=2 die nächsten 250 Mitarbeiter usw.
• Liegen für eine angeforderte Seite keine weiteren Mitarbeiter vor, wird eine leere JSON-Liste ([]) mit dem HTTP-Status-Code 200 zurückgegeben.

Zeiterfassung – Abruf der Gleitzeitstände¶

⚠️ Dieser Endpunkt wird bis Ende 2026 außer Betrieb genommen. Wechseln Sie auf die oben beschriebenen aktuellen Endpunkte.

Über diesen Endpunkt können Sie Gleitzeitstände automatisiert oder manuell abrufen. Dafür benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token.

Ihr Planerio Account Manager muss diesen Endpunkt zunächst aktivieren (Stichwort TIMESHEET_API_ARCHIVE_START_MONTH_YEAR). Der Abruf steht am Tag nach der Aktivierung zur Verfügung.

Die URL zum Datenabruf lautet:

https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/time-tracking

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token. Sie können den Datenabruf mit den folgenden Query-Parametern konfigurieren. Leiten Sie den ersten Parameter mit ? und alle weiteren Parameter mit & ein.

Folgende Daten sind enthalten (jeweils eine Zeile pro Mitarbeiter und Jahr/Monat):

Bei nachträglichen Korrekturen stehen die aktualisierten Werte in der Regel erst am folgenden Tag zur Verfügung.

ℹ️ Gibt dieser Endpunkt nach mehr als 20 Sekunden den HTTP-Status-Code 503 zurück, reduzieren Sie den abgefragten Zeitraum oder die Anzahl der Mitarbeiter. Mit separaten Schichtgruppen-Token können Sie die Mitarbeiterzahl begrenzen. Im Extremfall kann ein separates Token pro Schichtgruppe erforderlich sein.

Zeiterfassung – Erstellen und Importieren von Zeitstempeln¶

Über diesen Endpunkt können Sie Zeitstempel für Kommen und Gehen in Planerio erstellen. Sie verhalten sich wie Zeitstempel, die über Zeiterfassungshardware oder die mobile Planerio-App erstellt wurden. Die URL des Endpunkts lautet:

https://<host>/integrations/tokenapi/v2/aaa-bbb-ccc/timestampEvent

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token (siehe Abschnitt Konfiguration).

Zeitstempel können nur für Mitarbeiter erstellt werden, deren primäre Schichtgruppe mit dem verwendeten Schichtgruppen-Token verknüpft ist. Dadurch lässt sich der Zugriff auf bestimmte Schichtgruppen beschränken.

Folgende Parameter stehen zur Verfügung:

Übermitteln Sie die Felder in einem POST-Request. Beispiel mit curl:

curl -v \
  --data-urlencode 'personnel_number=001234' \
  --data-urlencode 'in_out=out' \
  --data-urlencode 'date_time=2020-05-23 19:13:37' \
  -H 'X-Planerio-Api-Gateway-Auth: SESSIONTOKEN' \
  'https://HOST/integrations/tokenapi/v2/AAA-BBB-CCC/timestampEvent'

Wurde der Zeitstempel erfolgreich gespeichert oder war bereits ein identischer Zeitstempel vorhanden, gibt der Endpunkt den HTTP-Status-Code 204 mit einem leeren Response-Body zurück.

Zeiterfassung – Abrufen von Zeitstempeln¶

Über diesen Endpunkt können Sie unverarbeitete Zeitstempel für Kommen und Gehen aus Planerio abrufen. Die URL des Endpunkts lautet:

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

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token (siehe Abschnitt Konfiguration). Folgende Query-Parameter stehen zur Verfügung. Leiten Sie den ersten Parameter mit ? und alle weiteren Parameter mit & ein.

Folgende Datenfelder werden pro Zeitstempel geliefert:

Lohnbuchhaltung – Abruf von manuellen Zuschlägen¶

Über diesen Endpunkt können Sie manuelle Zuschläge („Boni“) aus der vorbereitenden Lohnbuchhaltung abrufen. Automatisch vergebene Boni sind über diesen Endpunkt nicht verfügbar.

Verwenden Sie diesen Endpunkt erst nach Rücksprache mit Ihrem Planerio Account Manager.

Für den Datenabruf benötigen Sie ein im Abschnitt Konfiguration erstelltes Schichtgruppen-Token. Die URL lautet:

https://<host>/planerio/timetracking/payroll/api/external/token-api/aaa-bbb-ccc/manual-bonuses

Ersetzen Sie aaa-bbb-ccc durch das entsprechende Schichtgruppen-Token und hängen Sie die folgenden Query-Parameter an. Leiten Sie den ersten Parameter mit ? und alle weiteren Parameter mit & ein.

Folgende Daten sind in der Antwort enthalten (jeweils pro Bonus):