Planerio Public API¶

ℹ️ Wir entwickeln unsere Schnittstellen kontinuierlich weiter. Über die Ablösung von Endpunkten informieren wir mindestens drei Monate im Voraus.

Konfiguration¶

Die Schnittstelle kann im Administrationsbereich von Planerio aktiviert werden. Der Zugriff erfolgt über sogenannte „Schichtgruppen-Token“: Jedes Schichtgruppen-Token gewährt Zugriff auf die Daten einer oder mehrerer Schichtgruppen. Ein Benutzer mit administrativen Rechten muss dazu die folgende Konfiguration vornehmen:

Öffnen Sie Admin » Einstellungen:

Unten im rechten Bereich finden Sie die Box „Planerio-Schnittstelle“. Geben Sie einen aussagekräftigen Namen für den neuen Zugang ein, z. B. Zugriff für Controlling, und klicken Sie auf „Token erstellen“:

Planerio richtet einen neuen Zugang ein, den Sie anschließend einer oder mehreren Schichtgruppen zuweisen können:

Das „Schichtgruppen-Token“ ist in der Abbildung gelb markiert. Es wird für den Aufruf der meisten Endpunkte benötigt und beschränkt den Datenzugriff auf die zugewiesenen Schichtgruppen.

Mit den Optionen „Alle Schichtgruppen“, „Ausgewählte Schichtgruppen“ und „Alle Schichtgruppen außer ausgewählten“ legen Sie fest, welche Schichtgruppen bei Datenabrufen mit diesem Token berücksichtigt werden.

Es können mehrere Token angelegt werden. Wiederholen Sie diesen Schritt für jeden benötigten Zugang.

Für automatisierte Datenabrufe und -importe steht eine benutzerunabhängige Authentifizierung zur Verfügung.

Hierfür benötigen Sie ein technisches Login, das aus einem Benutzernamen und einem Passwort besteht. Diese Zugangsdaten unterscheiden sich vom regulären Mitarbeiter- oder Administrator-Login für Planerio und entsprechen dem folgenden Format:

Benutzer: REPORT04-BEISPIEL-3783035927
Passwort: ciFaL3IoTFBxNy9kazZWQ1A3M11SQnVrYzZIJCE=

Das technische Login erhalten Sie derzeit von Ihrem Planerio Account Manager. Stellen Sie dafür bitte folgende Informationen bereit:

Ihre Kundennummer sowie einen Ansprechpartner, an den die technischen Zugangsdaten übermittelt werden sollen
Zweck des Datenabrufs (erforderlich für die Datenschutzdokumentation)
Mobiltelefonnummer, die SMS empfangen kann (damit die Zugangsdaten nicht unverschlüsselt per E-Mail übermittelt werden müssen)

Sobald Ihnen die Zugangsdaten vorliegen, ermitteln Sie zunächst den in den folgenden Beispielen verwendeten Platzhalter <host>:

Wenn Sie über example.planer.io auf Planerio zugreifen, lautet der <host> example.api-gw.planer.io.
Anstelle von „example“ kann beispielsweise „praxis“, „krankenhaus“, „live“ oder eine Abkürzung Ihres Unternehmens stehen. In Einzelfällen, etwa nach einer Umfirmierung, kann der <host> von diesem Schema abweichen. Den gültigen Hostnamen erhalten Sie von Ihrem Planerio-Ansprechpartner oder unserem Support. Aus krankenhaus.planer.io wird nach diesem Schema beispielsweise krankenhaus.api-gw.planer.io.

Schritt 1 – Session-Token abrufen

Senden Sie einen GET-Request an https://<host>/partner-auth/v1/token und übermitteln Sie die technischen Zugangsdaten per HTTP-Basic-Authentifizierung. Ein Aufruf mit dem Kommandozeilenprogramm curl sieht beispielsweise so aus:

curl --user "REPORT04-BEISPIEL-3783035927:ciF…CE=" \
  https://<host>/partner-auth/v1/token

{
  "tokenString": "eyJra…GWZw",
  "tokenLifeTimeSeconds": 299
}

⚠️ Hier sind ausschließlich die technischen Zugangsdaten (siehe oben) zu verwenden,
kein Benutzer-/Admin-Login für die Planerio-Anwendung.
Bei gültigen Zugangsdaten gibt der Endpunkt ein JSON-Objekt mit einem JWT-Session-Token und dessen Lebensdauer in Sekunden zurück.

Schritt 2 – Session-Token nutzen, um API-Aufrufe durchzuführen

Übermitteln Sie das Session-Token aus Schritt 1 im Request-Header X-Planerio-API-Gateway-Auth.
Ein Aufruf mit curl sieht beispielsweise so aus:

curl -H 'X-Planerio-API-Gateway-Auth: eyJra…GWZw' \
    'https://<host>/planerio/planerio/planning/shifts/api/external/aaa-bbb-ccc/shifts?startDate=2021-03-01&endDate=2021-03-31'

Das Session-Token aus Schritt 1 kann innerhalb seiner Lebensdauer für beliebig viele Aufrufe genutzt werden.

️🔐 Speichern Sie die technischen Zugangsdaten sicher, beispielsweise in einem Cloud Secrets Manager oder in einer Datei, auf die nur autorisierte Benutzer Zugriff haben.

Legacy-Authentifizierung für angemeldete Planerio-Benutzer¶

Für Benutzer, die bereits über den Browser bei Planerio angemeldet sind, ist keine weitere Authentifizierung erforderlich. Sie können die Daten ihres Accounts wie unten beschrieben abrufen.

Stand Juli 2026 gilt dies nur für Endpunkte, deren Pfad nicht mit /planerio/ beginnt. Endpunkte mit diesem Präfix erfordern ein technisches Login. Für den interaktiven Zugriff auf diese Daten steht in der Regel ein eigener Menüpunkt in Planerio zur Verfügung.

Ersetzen Sie den in der folgenden Dokumentation verwendeten Platzhalter <host> durch den Hostnamen aus Ihrem Browser. Beispiele:

Lautet die URL in der Adresszeile beispielsweise https://example.planer.io/..., ist der <host> example.planer.io.
Anstelle von „example“ kann beispielsweise „praxis“, „krankenhaus“, „live“ oder eine Abkürzung Ihres Unternehmens stehen.

API-Bereiche¶

Aktualisiert am¶

Version vom 17. Juli 2026

Redaktionelle Überarbeitung.

Version vom 9. Juli 2026

Statt des bisherigen PDF-Dokuments stellen wir nun eine Online-Version mit der Dokumentation für Planerio 1.5 und 2.0 zur Verfügung.

Neue Endpunkte für tägliche und monatliche Zeitkontenwerte einschließlich Seitennummerierung dokumentiert.

Version vom 8. Januar 2026

Kapitel „Abruf von Mitarbeiter-Stammdaten“ um neue Werte ergänzt.

Version vom 23. Oktober 2025

Kapitel „Planung – Abruf des aktuellen Personalbedarfs“ um einen zusätzlichen Wert für die Feiertagsregelung ergänzt.

Version vom 7. August 2025

Kapitel „Planung – Abruf des aktuellen Personalbedarfs“ für den neuen Endpunkt überarbeitet.

Version vom 6. Juni 2025

Beispiel-URL und Felder in der Schichten-API korrigiert und aktualisiert.

Planerio Public API¶

Konfiguration¶

Authentifizierung über das „Technische Login“¶

Legacy-Authentifizierung für angemeldete Planerio-Benutzer¶

API-Bereiche¶

Aktualisiert am¶