PlanningPME

PlanningPME API - Entwicklerdokumentation

Verbinden Sie Ihren Zeitplan mit dem Rest Ihres Informationssystems.
PlanningPME ermöglicht den Lese- und Schreibzugriff auf Ihre Datenbank über eine spezielle API. Die PlanningPME-API folgt dem aktuellen Entwicklungsstandard (REST-Implementierung und JSON-formatierter Datentransport) für eine einfache Programmierung Ihrer Synchronisierungen und Integrationen.

Dieses Dokument enthält folgende Informationen:

PlanningPME-API basiert auf RESTful-Prinzipien, und das Standard-Datenübertragungsformat ist JSON.
Diese Dokumentation richtet sich hauptsächlich an Entwickler. Wir empfehlen, sich vor dem Weiterlesen zunächst mit der JSON-REST-API-Programmierung vertraut zu machen.

Dedizierte URL

Jeder PlanningPME-Kunde hat seine eigene dedizierte API-Adresse.
Angenommen, Ihr Markenname ist „MyCompany“, dann sollten Sie wahrscheinlich den Markenschlüssel „mycompany“ (Groß-/Kleinschreibung ignorieren) verwenden, um Ihre API-Adresse zu erstellen.
Dieser Schlüssel wird im weiteren Verlauf dieser Dokumentation als "your_brand" vermerkt.

Die Basis-API-Adresse einer Marke ist immer:
https://api.planningpme.com/your_brand/
oder
https://try.planningpme.com/your_brand/

Interaktive Dokumentation

Jede Marken-API präsentiert auch eine interaktive Dokumentation, die sehr nützlich ist, um Ihre PlanningPME-API-Methoden und -Modelle zu entdecken und API-Aufrufe zu erstellen.

Diese Dokumentation ist unter der folgenden Adresse verfügbar:
https://api.planningpme.com/your_brand/doc/index
oder
https://try.planningpme.com/your_brand/doc/index

Interaktive Dokumentation

Diese beiden Adressen können nicht ohne Präsentation eines Anwendungsschlüssels aufgerufen werden.

Sicherheit

1/ Präsentation des Anwendungsschlüssels

Sie benötigen einen Anwendungsschlüssel (Appkey), um auf Ihre API zuzugreifen und so die aufrufende Anwendung zu identifizieren.
Dieser Appkey ist in Ihrem PlanningPME-Konto oder auf Anfrage an unseren Support verfügbar.
Zusätzlich zur Sicherung des API-Zugriffs können Sie mit dem Appkey einer Partner- oder Tier-Anwendung Zugriff gewähren, indem Sie diesen Programmen einen eigenen Schlüssel zur Identifizierung ihrer Aufrufe an die API geben.

Der Appkey sollte immer im Header eines API-Aufrufs übergeben werden, indem ein dedizierter „X-APPKEY“-Header verwendet wird.

GET /your_brand/api/config HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac

Um auf Ihre interaktive Dokumentation zuzugreifen, verwenden Sie Ihren Appkey als Abfrageparameter, wie im folgenden Beispiel:

https://api.planningpme.com/your_brand/doc/index?appkey=e991573da5ffd4sab9b1e26bc6b64aac

2/ Benutzer-Token und Identitätsnachweis

Die meisten API-Aufrufe sollten benutzerauthentifiziert sein, um beim Datenzugriff einen Identitätsnachweis zu verwenden und definierte Benutzer- und Gruppenberechtigungen zu respektieren.

Eine Autorisierung wird erteilt, indem Benutzername und Passwort an die API übermittelt werden und dann ein Token erhalten wird, das zur Authentifizierung oder zum Identitätsnachweis jedes nachfolgenden API-Aufrufs verwendet wird.

Der Erhalt eines Autorisierungs-Tokens erfolgt immer durch die Übertragung dieser Daten auf die "/token"-Url.

POST /votre_marque/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac

grant_type=password&username=Ihr_Benutzername&password=Ihr_Passwort

Im Falle einer erfolgreichen Authentifizierung enthält die Antwortstruktur ein JSON-Element wie folgt.

{
    "access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH",
    "token_type": "bearer",
    "expires_in": 86399,
    "username": "Ihr_Benutzername"
}

Der Wert des Merkmals "access_token" sollte dann in nachfolgenden autorisierten Anfragen an die API verwendet werden.
Und wie durch das Merkmal "token_type" angezeigt wird, ist dieser Wert ein Inhaber-Token.

Jeder nachfolgende autorisierte Aufruf sollte dann den "Autorisierung"-Header mit diesem spezifischen "Inhaber"-Wert aufweisen.

POST /your_brand/api/customer HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Authorization: Bearer KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_oUzBbR0PoEQfOb_O7m5BrLz9vwDzV_YjtRRrQ_7QxYnxO9uZs38SJ7UxTjDZgx_JKRUoZ3Wk6RNnXRpSkcmOrINvJLDMYXptYFiTjn9Op-vkPdtOKFp9M1cNjrH1ho2uaRBpUUMH_vJ-8W8mTH9wgFrJlecGIpntb7jet2GYpGs3Is0gcH

Verwendung der API

1/ Allgemeine Datenüberlegungen

a) Modelle

Sie können PlanningPME-Datenmodelle leicht durch die Verwendung der interaktiven Dokumentation Ihrer API entdecken.

b) Datumsformat

Das von der API verwendete und in jeder JSON-Anfrage erwartete Datumsformat ist das ISO 8601 Format. Ex:

2018-01-25T18:05:00Z

c) Sortierlisten

GET-Methoden verwenden oft einen „sortInfo“-Parameter, um die Sortierreihenfolge der zurückgegebenen vollständigen/paginierten Liste festzulegen.

Diese Information besteht aus dem Namen eines Merkmals, direkt gefolgt von einem + oder - Zeichen.
Verwenden Sie beispielsweise „label+“, um in aufsteigender Reihenfolge nach dem „label“-Merkmal zu sortieren.

Es ist auch möglich, mehrere Aufträge durch Anhängen zu kombinieren.
Verwenden Sie beispielsweise „notValid-label+“, um in absteigender Reihenfolge nach dem Merkmal „notValid“ und dann in aufsteigender Reihenfolge nach dem Merkmal „label“ zu sortieren.

Beachten Sie, dass bei Merkmal-Labels die Groß- und Kleinschreibung beachtet werden muss.

d) Konstante Aufzählungen

Eine vollständige Liste der mit Ihrer API-Version verwendeten Enums erhalten Sie durch den Aufruf der „/api/config“-Methode. Diese Liste kann nicht geändert werden, es sei denn, sie wird in Zukunft ergänzt.

GET /your_brand/api/config HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac

Nachfolgend finden Sie die Liste der Enums für die Version 4.1.1.117 der API.

{
  ...
  enums: {
    "Access": {
      "All": 0,
      "Read": 82,
      "Write": 87
    },
    "BillingType": {
      "Package": 0,
      "Unit": 1
    },
    "ConstraintAction": {
      "NoTaskBeforeNbHours": 0,
      "NoTaskBeforeNbDays": 1,
      "NoTaskSamePeriod": 2,
      "NbMaxHours": 3,
      "NbMax": 4,
      "DurationMaxHours": 5,
      "DurationMaxDays": 6
    },
    "ConstraintFor": {
      "All": 0,
      "Resources": 1,
      "Departments": 2
    },
    "ConstraintIf": {
      "Nothing": 0,
      "Nb": 1,
      "NbHours": 2,
      "Begin": 3,
      "End": 4
    },
    "ConstraintOp": {
      "Nothing": 0,
      "Equal": 1,
      "Inf": 2,
      "InfEqual": 3,
      "Sup": 4,
      "SupEqual": 5,
      "Before": 6,
      "After": 7
    },
    "ConstraintType": {
      "Task": 0,
      "Unavailability": 1
    },
    "ConstraintWhat": {
      "LabelAll": 0,
      "LabelExact": 1,
      "LabelBegin": 2
    },
    "ConstraintWhen": {
      "Nothing": 0,
      "Day": 1,
      "Week": 2,
      "Month": 3,
      "Year": 4
    },
    "CustomerType": {
      "Individual": 1026,
      "Company": 1027
    },
    "DataFieldType": {
      "Date": 1,
      "Time": 2,
      "Text": 3,
      "Numeric": 4,
      "Double": 5,
      "Combo": 6,
      "Link": 7,
      "Check": 8,
      "Memo": 9,
      "Separator": 10,
      "File": 11,
      "Position": 12,
      "SignatureMobile": 13,
      "Hyperlink": 16,
      "Startdate": 17,
      "Enddate": 18,
      "Duration": 19,
      "Signature": 20
    },
    "DescriptionFieldType": {
      "Index1": 49,
      "Index2": 50,
      "EmailBody": 69,
      "Label": 76,
      "Mobile": 77,
      "Calendar": 79,
      "EmailSubject": 83,
      "Tooltip": 84
    },
    "Destination": {
      "Task0": 48,
      "Task2": 50,
      "Task3": 51,
      "Task4": 52,
      "Task5": 53,
      "Equipment0": 65,
      "Customer1": 67,
      "MaterialResource1": 77,
      "MaterialResource2": 78,
      "MaterialResource3": 79,
      "Project0": 80,
      "HumanResource1": 82,
      "HumanResource2": 83,
      "Task1": 84,
      "HumanResource3": 86,
      "Customer0": 97,
      "HumanResource0": 98,
      "Customer2": 99,
      "MaterialResource0": 100
    },
    "DestinationType": {
      "Task": 0,
      "Customer": 1,
      "Equipment": 2,
      "Resource": 3,
      "Project": 4
    },
    "HistoryOp": {
      "Insert": 65,
      "Delete": 68,
      "Email": 69,
      "Invitation": 73,
      "Update": 85
    },
    "HistoryType": {
      "Customer": 67,
      "Unavailability": 73,
      "Project": 80,
      "Resource": 82,
      "Task": 84
    },
    "JsonWritingType": {
      "Normal": 1,
      "KeyLabel": 2,
      "String": 3,
      "Data": 4
    },
    "LicenseStatus": {
      "Other": 0,
      "Evaluation": 1,
      "Ok": 2,
      "NoExpirationDate": -8,
      "WrongDatabase": -7,
      "WrongMachine": -6,
      "ResourceCount": -5,
      "LicenseCount": -4,
      "Expired": -3,
      "Empty": -2,
      "Corrupted": -1
    },
    "NotificationType": {
      "None": 0,
      "TaskInsert": 1,
      "TaskUpdate": 2,
      "UnavailabilityInsert": 4,
      "UnavailabilityUpdate": 8
    },
    "OneOrMoreCustomers": {
      "OneCustomer": 1422,
      "MoreCustomer": 1423
    },
    "OneOrMoreResources": {
      "OneResource": 1076,
      "MoreResource": 1077
    },
    "RecurrenceDaily": {
      "AllThe": 1255,
      "AllWorkingDays": 1256
    },
    "RecurrenceMonthly": {
      "Date": 1258,
      "Day": 1259
    },
    "RecurrenceMonthlyDayWhich": {
      "First": 0,
      "Second": 1,
      "Third": 2,
      "Fourth": 3,
      "Last": 4
    },
    "RecurrenceRange": {
      "NoEndDate": 1250,
      "EndThe": 1252
    },
    "RecurrenceType": {
      "Daily": 1246,
      "Weekly": 1247,
      "Monthly": 1248,
      "Yearly": 1249
    },
    "ResourceFilter": {
      "All": 40960,
      "Human": 45056,
      "Material": 49152,
      "ToPlan": 53248
    },
    "ResourceType": {
      "Human": 1035,
      "Material": 1036,
      "ToPlan": 1537
    },
    "TaskType": {
      "Default": 1467,
      "Duration": 1468,
      "Time": 1469
    },
    "Title": {
      "Miss": 0,
      "Mr": 1,
      "Ms": 2
    },
    "TimeLapseUnit": {
      "Day": 0,
      "Week": 1,
      "Month": 2,
      "Year": 3
    },
    "TypeHatch": {
      "BDIAGONAL": 0,
      "CROSS": 1,
      "DIAGCROSS": 2,
      "FDIAGONAL": 3,
      "HORIZONTAL": 4,
      "VERTICAL": 5
    },
    "WorkCapacity": {
      "Hours": 1590,
      "Slots": 1591
    }
  }
  ...

e) Antwortsprache

Die in Antworttexten wie z. B. Fehlermeldungen verwendete Sprache kann mit dem Header "Accept-Language" angegeben werden.

Accept-Language: de

Die in der PlanningPME-API und im PlanningPME-WebAccess verfügbaren Sprachen sind: Dänisch (da), Niederländisch (nl), Englisch (en), Finnisch (fi), Französisch (fr), Deutsch (de), Italienisch (it), Norwegisch (no), Polnisch (pl), Russisch (ru), Spanisch (es), Schwedisch (sv).

2/ Beispiele für API-Aufrufe

In den nachfolgenden Beispielen wird der Anwendungsschlüssel als "Ihr_Schlüssel" und das Inhaber-Token als "Ihr_Token" vermerkt. Bitte ersetzen Sie diese durch Ihre eigenen Werte.

/api/task

→ Erhalten Sie eine vollständige oder paginierte Liste von Aufgaben mit der Methode GET "/api/task".

GET /your_brand/api/task?pageIndex=1&pageSize=20&sortInfo=label+ HTTP/1.1
Host: api.planningpme.com
X-APPKEY: Ihr_Schlüssel
Authorization: Bearer Ihr_Token

Gibt eine Reihe von Aufgaben zurück, die eine zweite Seite mit 20 Aufgaben enthält, die nach absteigender Bezeichnung geordnet sind.

{
  "totalItems": 97,
  "items": [
    {
      "key": 756,
      "label": "Cours d'anglais pour enfant",
      "type": 1467,
      "style": {
        "backgroundColor": "#65A18D",
        "color": "#000000"
      }
    },
	...
    {
      "key": 131,
      "label": "Coaching",
      "type": 1467,
      "style": {
        "backgroundColor": "#214DE9",
        "color": "#000000"
      }
    }
  ]
}

→ Erhalen Sie eine detaillierte Aufgabe mit der Methode GET "/api/task/{id}".

GET /your_brand/api/task/756 HTTP/1.1
Host: api.planningpme.com
X-APPKEY: votre_clé
Authorization: Bearer Ihr_Token

Gibt eine detaillierte Repräsentation des Aufgabenobjekts der Aufgabe mit der ID 756 zurück.

{
  "key": 756,
  "label": "Cours d'anglais pour enfant",
  "type": 1467,
  "style": {
    "backgroundColor": "#65A18D",
    "color": "#000000"
  },
  "skills": [
    [
      {
        "key": 12,
        "name": "Enfant",
        "label": "Pédagogie > Enfant",
        "level": 1,
        "domain": {
          "key": 4,
          "label": "Pédagogie"
        }
      },
      {
        "key": 83,
        "name": "Anglais",
        "label": "Langue > Anglais",
        "level": 1,
        "domain": {
          "key": 4,
          "label": "Langue"
        }
      }
    ]
  ]
}