Planerio Public API¶

ℹ️ Wir entwickeln unsere Schnittstelle(n) regelmäßig für Sie weiter. Über Endpunkte, die ersetzt werden, informieren wir mindestens 3 Monate im Voraus.

Konfiguration¶

Die Schnittstelle kann über den Administrations-Bereich in Planerio aktiviert werden. Der Zugang wird jeweils durch ein sogenanntes „Schichtgruppen-Token“ aktiviert: jedes Schichtgruppen-Token repräsentiert den Zugriff auf die Daten von einer oder mehreren Schichtgruppen. Dazu ist folgende Konfiguration durch einen Benutzer mit administrativen Rechten vorzunehmen:

Öffnen von Admin » Einstellungen:

Im rechten Bereich ganz unten finden Sie die Box „Planerio-Schnittstelle“. Vergeben Sie hier einen informativen Namen für den zu erstellenden Zugang, z.B. hier Zugriff für Controlling, und klicken Sie auf den Button „Token erstellen“:

Es wird nun ein neuer Zugang eingerichtet, den Sie anschließend einer oder mehrerer Schichtgruppen zuweisen können:

Hier im Bild ist das „Schichtgruppen-Token“ gelb markiert. Dieses wird zum Aufruf der meisten Schnittstellen (siehe nachfolgende Kapitel der Dokumentation) benötigt und dient nur dazu, den Abruf von Daten einzelner Schichtgruppen zu segmentieren.

Über die Auswahl „Alle Schichtgruppen“ / „Ausgewählte Schichtgruppen“ / „Alle Schichtgruppen außer ausgewählten“ können Sie steuern, welche Schichtgruppen im Datenabruf über dieses Schichtgruppen-Token berücksichtigt werden.

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

Authentifizierung über das „Technische Login“¶

Falls Sie automatisiert Daten über die Schnittstelle abrufen oder importieren möchten, steht dafür eine Nutzer-unabhängige Authentifizierung zur Verfügung.

Hierfür benötigen Sie ein technisches Login, bestehend aus Benutzername und Password. Diese unterscheiden sich vom normalen Mitarbeiter-/Admin-Login für Planerio und sehen ähnlich wie im folgenden Beispiel aus:

Benutzer: REPORT04-BEISPIEL-3783035927
Passwort: ciFaL3IoTFBxNy9kazZWQ1A3M11SQnVrYzZIJCE=

Dieses technische Login müssen Sie aktuell bei Ihrem Planerio-Account Manager erfragen Bitte stellen Sie uns folgende Informationen zur Verfügung:

• Ihre Kundennummer sowie einen Ansprechpartner, an den die technischen Zugangsdaten übermittelt werden sollen

• Zweck des Datenabrufs (wichtig für Datenschutz-Dokumentation)

• Handynummer, die SMS empfangen kann (wichtig, um die Zugangsdaten nicht unverschlüsselt per E-Mail übertragen zu müssen)

Sobald Ihnen diese Zugangsdaten vorliegen, gilt es als erstes, den in allen weiteren Beispielen benutzten Platzhalter <host> zu ermitteln. Gehen Sie dazu wie folgt vor:

• Sie greifen über example.planer.io auf Planerio zu → der <host> ist: example.api-gw.planer.io
• Statt „example“ finden Sie möglicherweise „praxis“, „krankenhaus“, „live“, oder eine Abkürzung für Ihre Firma oder Firmengruppe. In einzelnen Fällen (z.B. Umfirmierung) kann der hiervon abweichen. Das erfahren Sie von Ihrem Planerio-Ansprechpartner oder unserem Support. Dementsprechend würde sich z.B. aus krankenhaus.planer.io folgender <host> ergeben: krankenhaus.api-gw.planer.io

Schritt 1 – Session-Token abrufen

• Hierzu steht der Endpunkt https://<host>/partner-auth/v1/token zur Verfügung, der ein GET-Request mit den oben erwähnten technischen Zugangsdaten als „Basic“-Authentifizierung erwartet. Mit dem CLI-Tool „curl“ könnte das z.B. so aussehen:

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.

• Im Falle gültiger Zugangsdaten wird ein JWT-Session-Token und die Lebensdauer dieses Session-Tokens in Sekunden in einem JSON-Object zurückgegeben, wie im Beispiel gezeigt.

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

• Das Session-Token aus Schritt 1 muss nun im Request Header X-Planerio-API-Gateway-Auth mitgegeben werden.

• Mit dem CLI-Tool „curl“ könnte das z.B. so aussehen:

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.

️🔐 Bitte speichern Sie die technischen Zugangsdaten so gut gesichert wie möglich ab, z.B. in einem Cloud Secrets Manager, oder in einer Datei, auf die nur bestimmte Benutzer Zugriff haben.

Legacy-Authentifizierung – für in Planerio eingeloggte Nutzer¶

Für Nutzer, die bereits im Browser in Planerio eingeloggt sind, ist keine weitere Authentifizierung erforderlich. Sie können die Daten aus Ihrem Account wie unten beschrieben abrufen.

️Stand Juli 2026 gilt das nur für Endpunkte, deren Pfad nicht mit /planerio/ beginnt. Für diese ist nur das technische Login möglich. Für den interaktiven Zugriff aus dem Browser auf diese Daten steht i.d.R. ein eigener Menüpunkt zur Verfügung.

In der Dokumentation unten erscheint der Platzhalter <host>. Diesen Platzhalter ersetzen Sie dabei bitte durch den Hostname aus Ihrem Browser, zum Beispiel:

• Sie sehen im Browser beim Zugriff auf Planerio in der Adresszeile z.B. https://example.planer.io/... → der <host> ist: example.planer.io
• Statt „example“ finden Sie möglicherweise „praxis“, „krankenhaus“, „live“, oder eine Abkürzung für Ihre Firma oder Firmengruppe.

API-Bereiche¶

• Stammdaten
• Planung
• Abwesenheiten
• Zeiterfassung & Lohnbuchhaltung

Aktualisiert am¶

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.

Version vom 8. Januar 2026

Kapitel “Abruf von Mitarbeiter-Stammdaten” aktualisiert. (neue Werte)

Version vom 23. Oktober 2025

Kapitel “Planung – Abruf des aktuellen Personalbedarfs” aktualisiert (zusätzlicher Wert bei Feiertagsregelung).

Version vom 7. August 2025

Kapitel “Planung – Abruf des aktuellen Personalbedarfs” überarbeitet (neuer Endpunkt).

Version vom 6. Juni 2025

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

Version vom 15. Oktober 2024

In Planerio 1.5 und 2.0 ist der Zwischenschritt einer Planungsvorlage entfallen. Ein sich darauf beziehender Parameter, der bereits ohne Funktion war, ist jetzt auch aus der Dokumentation entfernt.

Version vom 24. September 2024

Ab Planerio-Version v24.06.2 – Einmaliger Import von Abwesenheitsperioden über Schnittstelle ist für Planerio 1.5 dokumentiert.

Version vom 22. Juli 2024

Dokumentation in separate Dokumente für Planerio-Versionen getrennt.