Generelles

Die Daten werden als JSON Files unformatiert übertragen. Für eine für den Menschen schöne Darstellung der JSON Dokumente benutzen Sie zum Beispiel http://jsonprettyprint.com

Vorbereitung: Einen API-Benutzer erstellen

Für die Benutzung der API ist ein dedizierter, normaler Planik-Benutzer zwingend nötig. Mit diesem muss man sich zu Beginn der Nutzung der Web-API einlogen (Endpoint /login, siehe weiter unten). Man erhält so drei Tokens, welche für die eigentlichen Aufrufe mitgegeben werden müssen. Das alles wird im folgenden Text anschaulich erklärt.

Der Benutzer können Sie als Kunde selbst in Planik erstellen. Er muss lesenden Zugriff haben oder, für schreibende Endpoints, schreibenden Zugriff. D.h, im ersten Fall reicht ein Benutzer mit der Planik-Rolle "Leser", sonst aber ist die Rolle "Planer" nötig.


Vorgehen:

  1. In Planik mit einem Planer-Login einloggen und unter Einstellungen -> Benutzer einen normalen Planik-Benutzer apireader@mycompany.ch (oder sonst eine Emailadresse) mit der Rolle "Leser" erstellen. Mit diesem technischen Benutzer erfolgt dann die Authentifizierung auf der Web API. Die Emailadresse muss existieren, so dass das Bestätigungsemail erhalten.
  2. Das Bestätigungsemail an apireader@mycompany.ch abrufen. Es enthält einen Link zum Setzen des Passwortes. Logen Sie sich vor dem Anklicken des Links vorsichtshalber aus Planik aus.
  3. Das Passwort über den Link setzen. In diesem Beispiel nehmen wir das Passwort 6vqzB2ZVoYj27NmFtFmY.

Erstens: auf Web API einloggen

Um die Schnittstelle anzutesten ist ein Kommandozeilenprogramm wie cUrl zu empfehlen. Mit diesem können beliebige teschnische API-Calls ausgeführt werden. Das Programm ist unter Linux meist bereits installiert und kann auch unter Windows und OS X installiert und genutzt werden. cUrl wird in der folgenden Beschreibung genutzt.


Das Login erfolgt durch den Aufruf des Endpoints /login. Die Abfrage mit cUrl sieht so aus:

 curl -i \
 -H 'Content-Type: application/json' \
 -d '{"benutzer": {"email": "apireader@mycompany.ch", "password": "6vqzB2ZVoYj27NmFtFmY"}}' \
 https://api.planik.ch/api/v1/login

Zurück kommen drei verschiedene Headers, welch ausgegeben werden und man für die späteren Aufrufe verwenden wird:

  • access-token (hier: f2FLH8Xpo1ZQnt5OOdCP4g)
  • client (hier: pDumX4XC_34BS_2fN0_5jQ
  • uid (hier: apireader@mycompany.ch)

Zweitens: Daten per Web API abfragen

Ein Aufruf der API sieht mit den eben gewonnen drei Login-Tokens wie folgt aus. Hier fragen wir eine Liste aller Dienstvorlagen im Team 999 ab, es ist der Aufruf des Endpoints /dienstvorlagen:


Die Id-Nummer des Teams, hier beim folgenden Aufruf 999, kann beim Support von Planik nachgefragt werden.

curl -i -g \
-H 'Accept: application/json' \
-H 'access-token:f2FLH8Xpo1ZQnt5OOdCP4g' \
-H 'uid:apireader@mycompany.ch' \
-H 'client:pDumX4XC_34BS_2fN0_5jQ' \
'https://api.planik.ch/api/v1/dienstvorlagen?filter[mandant_id]=999'

Das Resultat im Body ist eine Liste aller Dientsvorlagen im Team 999:

{
  "data": [
    {
      "id": "123456",
      "type": "dienstvorlage",
      "attributes": {
        "kuerzel": "T1",
        "schluessel_dienst_typ": "DIENST",
        "zeit_von": "2000-01-01T08:00:00+01:00",
        "zeit_bis": "2000-01-01T17:00:00+01:00",
        "legende": "Tagdienst",
        "notiz": null,
        "pause_zeit_von": "2000-01-01T12:00:00+01:00",
        "pause_zeit_bis": "2000-01-01T12:30:00+01:00",
        "schlagworte": []
      }
    },
    etc.

Mit den selben drei Login-Tokens können für 24 Stunden weitere API Aufrufe gemacht werden.


Hier geht es zur Liste aller API-Calls.


Viel Spass.