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:

Wie ermitteln Sie Ihre PlanningPME-API-Adresse?
Wo finden Sie Ihre interaktive Dokumentation?
Wie wird die Sicherheit in der PlanningPME-API implementiert?
Was sind die allgemeinen Datenüberlegungen in der PlanningPME-API?
Wie erstellen Sie Ihre ersten Anfragen an die PlanningPME-API?

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.

Interaktive Dokumentation

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

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

Anmerkung: Falls die Kontoauthentifizierung auf Ihrer API aktiviert ist, erfolgt der Zugriff auf die interaktive Dokumentation mit einem Klick innerhalb der PlanningPME-Kontoanwendung.

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 verfügbar (wenn die Kontoauthentifizierung auf Ihrer API aktiviert ist), oder auf Anfrage beim Support.
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 den Appkey als Adressparameter, wie im folgenden Beispiel.

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

2/ Benutzer-Token und Identitätsnachweis

Die meisten API-Anfragen müssen auch einen Berechtigungsjeton aufweisen, um das Profil des Benutzers zu bestimmen, der auf die Daten zugreift, und um die in der Anwendung definierten Benutzer- und Gruppenberechtigungen einzuhalten.

Dieses Token wird zuvor bei der Authentifizierung eines Benutzers an der Adresse /token erhalten und ist acht Stunden lang gültig.

Die an diese Adresse geposteten Daten unterscheiden sich je nach der für Ihre Anwendung gewählten Authentifizierungsmethode.

a) Klassische Authentifizierung

Wenn sie aktiviert ist, erfolgt die klassische Authentifizierung durch Eingabe des Benutzernamens (username) und des Passworts (password).

POST /your_brand/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=Ihr_Benutzername&password=Ihr_Passwort

b) Kontoauthentifizierung

Wenn sie aktiviert ist, erfolgt die Kontoauthentifizierung durch Hinterlegung eines Dienstkonto-Tokens, das zuvor in der PlanningPME-Kontoanwendung bezogen wurde.

API PlannningpmE

Für jeden hier aufgelisteten Benutzer können Sie das Dienstkonto-Token in Ihre Zwischenablage kopieren.

Beziehen Sie nun ein Autorisierungs-Token von Ihrer API, indem Sie das kopierte Konto-Token (Assertion) posten.

POST /your_brand/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=account_token

c) Verwendung des Autorisierungstokens

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

{
    "access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_...3Is0gcH",
    "token_type": "bearer",
    "expires_in": 86399,
    "username": "Ihr_Benutzername"
}

Die Eigenschaft "access_token" enthält das Token für die API-Autorisierung.

Auch ist dieses Token, wie durch die Eigenschaft "token_type" angegeben, vom Typ "bearer". Anfragen, die eine Autorisierung erfordern, müssen daher den Header "Authorization" mit dem Wert "Bearer" aufweisen, wie im folgenden Beispiel.

POST /your_brand/api/customer HTTP/1.1
Host: api.planningpme.com
X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
Authorization: Bearer KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_...3Is0gcH

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 die Liste der Enums in Version 4.7.0.26

{
...
"enums": {
  "Access": {
    "All": "All",
    "Read": "Read",
    "Write": "Write"
  },
  "BillingType": {
    "Package": "Package",
    "Unit": "Unit"
  },
  "ColorDepending": {
    "Label": "Label",
    "Category": "Category",
    "Customer": "Customer",
    "Time": "Time",
    "Project": "Project"
  },
  "ConfigType": {
    "ExportTemplates": "ExportTemplates",
    "TimeRestrictedView": "TimeRestrictedView",
    "Filterings": "Filterings",
    "Language": "Language",
    "DateTimeFormat": "DateTimeFormat",
    "GCSync": "GCSync",
    "EffectTemplates": "EffectTemplates",
    "SyncResource": "SyncResource",
    "PrintTemplates": "PrintTemplates"
  },
  "ConstraintAction": {
    "NoTaskBeforeNbHours": "NoTaskBeforeNbHours",
    "NoTaskBeforeNbDays": "NoTaskBeforeNbDays",
    "NoTaskSamePeriod": "NoTaskSamePeriod",
    "NbMaxHours": "NbMaxHours",
    "NbMax": "NbMax",
    "DurationMaxHours": "DurationMaxHours",
    "DurationMaxDays": "DurationMaxDays"
  },
  "ConstraintFor": {
    "All": "All",
    "Resources": "Resources",
    "Departments": "Departments"
  },
  "ConstraintIf": {
    "Nothing": "Nothing",
    "Nb": "Nb",
    "NbHours": "NbHours",
    "Begin": "Begin",
    "End": "End"
  },
  "ConstraintOp": {
    "Nothing": "Nothing",
    "Equal": "Equal",
    "Inf": "Inf",
    "InfEqual": "InfEqual",
    "Sup": "Sup",
    "SupEqual": "SupEqual",
    "Before": "Before",
    "After": "After"
  },
  "ConstraintType": {
    "Task": "Task",
    "Unavailability": "Unavailability"
  },
  "ConstraintWhat": {
    "LabelAll": "LabelAll",
    "LabelExact": "LabelExact",
    "LabelBegin": "LabelBegin"
  },
  "ConstraintWhen": {
    "Nothing": "Nothing",
    "Day": "Day",
    "Week": "Week",
    "Month": "Month",
    "Year": "Year"
  },
  "CountHolidays": {
    "Five": "Five",
    "Six": "Six"
  },
  "CurrencyCode": {
    "GBP": "GBP",
    "EUR": "EUR",
    "USD": "USD",
    "DEM": "DEM",
    "FRF": "FRF",
    "CHF": "CHF",
    "ARS": "ARS",
    "BRL": "BRL",
    "CLP": "CLP",
    "CRC": "CRC",
    "RUB": "RUB",
    "GTQ": "GTQ",
    "PAB": "PAB",
    "PYG": "PYG",
    "PEN": "PEN",
    "UYU": "UYU",
    "SVC": "SVC",
    "HNL": "HNL",
    "NOK": "NOK",
    "CNY": "CNY",
    "JPY": "JPY",
    "CAD": "CAD"
  },
  "CustomerType": {
    "Individual": "Individual",
    "Company": "Company"
  },
  "DataFieldType": {
    "Date": "Date",
    "Time": "Time",
    "Text": "Text",
    "Numeric": "Numeric",
    "Double": "Double",
    "Combo": "Combo",
    "Link": "Link",
    "Check": "Check",
    "Memo": "Memo",
    "Separator": "Separator",
    "File": "File",
    "Position": "Position",
    "SignatureMobile": "SignatureMobile",
    "Hyperlink": "Hyperlink",
    "ProjectStartDate": "ProjectStartDate",
    "ProjectEndDate": "ProjectEndDate",
    "ProjectDuration": "ProjectDuration",
    "ProjectDeadline": "ProjectDeadline",
    "ProjectDeadlineOver": "ProjectDeadlineOver",
    "Signature": "Signature",
    "ProjectEstimateDuration": "ProjectEstimateDuration",
    "SubProjectEstimateDuration": "SubProjectEstimateDuration"
  },
  "DescriptionFieldType": {
    "Index1": "Index1",
    "Index2": "Index2",
    "EmailBody": "EmailBody",
    "Label": "Label",
    "Mobile": "Mobile",
    "CalendarBody": "CalendarBody",
    "EmailSubject": "EmailSubject",
    "Tooltip": "Tooltip",
    "LabelAssignment": "LabelAssignment",
    "CalendarSubject": "CalendarSubject",
    "Print": "Print",
    "LabelUnavailability": "LabelUnavailability",
    "PrintUnavailability": "PrintUnavailability"
  },
  "DescriptionFieldStyle": {
    "Normal": "Normal",
    "Bold": "Bold",
    "Italic": "Italic",
    "Underline": "Underline"
  },
  "DescriptionFieldColor": {
    "Custom": "Custom",
    "Default": "Default",
    "Destination": "Destination"
  },
  "Destination": {
    "Task0": "Task0",
    "Task2": "Task2",
    "Task3": "Task3",
    "Task4": "Task4",
    "Task5": "Task5",
    "Equipment0": "Equipment0",
    "Customer1": "Customer1",
    "MaterialResource1": "MaterialResource1",
    "MaterialResource2": "MaterialResource2",
    "MaterialResource3": "MaterialResource3",
    "Project0": "Project0",
    "HumanResource1": "HumanResource1",
    "HumanResource2": "HumanResource2",
    "Task1": "Task1",
    "HumanResource3": "HumanResource3",
    "Customer0": "Customer0",
    "HumanResource0": "HumanResource0",
    "Customer2": "Customer2",
    "MaterialResource0": "MaterialResource0",
    "Customer3": "Customer3",
    "Project1": "Project1",
    "Project2": "Project2",
    "SubProject0": "SubProject0",
    "Project3": "Project3"
  },
  "DestinationType": {
    "Task": "Task",
    "Customer": "Customer",
    "Equipment": "Equipment",
    "Resource": "Resource",
    "Project": "Project",
    "SubProject": "SubProject"
  },
  "DoMode": {
    "None": "None",
    "End": "End",
    "Duration": "Duration"
  },
  "EffActionType": {
    "Email": "Email",
    "Sms": "Sms",
    "MicrosoftOutlook": "MicrosoftOutlook",
    "GoogleCalendar": "GoogleCalendar"
  },
  "EffIfType": {
    "Category": "Category",
    "Status": "Status"
  },
  "EffIfOp": {
    "IsIn": "IsIn",
    "BecomesIn": "BecomesIn"
  },
  "EffSourceType": {
    "Customer": "Customer",
    "Resource": "Resource",
    "Project": "Project",
    "Status": "Status",
    "ResourceIn": "ResourceIn",
    "ProjectIn": "ProjectIn",
    "TaskIn": "TaskIn",
    "Assignment": "Assignment",
    "Unavailability": "Unavailability",
    "Task": "Task"
  },
  "EffStepType": {
    "Start": "Start",
    "End": "End",
    "Insert": "Insert",
    "Delete": "Delete",
    "Unperiodize": "Unperiodize",
    "Update": "Update"
  },
  "EffSubjectType": {
    "Assignment": "Assignment",
    "Unavailability": "Unavailability",
    "Task": "Task"
  },
  "EffTargetType": {
    "Customer": "Customer",
    "Resource": "Resource",
    "User": "User",
    "Account": "Account"
  },
  "HistoryOp": {
    "Insert": "Insert",
    "Delete": "Delete",
    "Email": "Email",
    "Invitation": "Invitation",
    "Unperiodize": "Unperiodize",
    "Session": "Session",
    "Update": "Update"
  },
  "HistoryType": {
    "Assignment": "Assignment",
    "Customer": "Customer",
    "SessionDesktop": "SessionDesktop",
    "Unavailability": "Unavailability",
    "SessionMobile": "SessionMobile",
    "Project": "Project",
    "Resource": "Resource",
    "Task": "Task",
    "SessionWebAccess": "SessionWebAccess"
  },
  "InRootType": {
    "Customer": "Customer",
    "Project": "Project",
    "Resource": "Resource"
  },
  "JoinStatus": {
    "Invited": "Invited",
    "Connected": "Connected"
  },
  "JsonWritingType": {
    "None": "None",
    "Normal": "Normal",
    "KeyLabel": "KeyLabel",
    "String": "String",
    "Data": "Data"
  },
  "LicenseStatus": {
    "Other": "Other",
    "Evaluation": "Evaluation",
    "Ok": "Ok",
    "NoExpirationDate": "NoExpirationDate",
    "WrongDatabase": "WrongDatabase",
    "WrongMachine": "WrongMachine",
    "ResourceCount": "ResourceCount",
    "LicenseCount": "LicenseCount",
    "Expired": "Expired",
    "Empty": "Empty",
    "Corrupted": "Corrupted"
  },
  "LinkRefType": {
    "Assignment": "Assignment",
    "Customer": "Customer",
    "Unavailability": "Unavailability",
    "Project": "Project",
    "Resource": "Resource",
    "Task": "Task"

  },
  "NotificationType": {
    "None": "None",
    "TaskInsert": "TaskInsert",
    "TaskUpdate": "TaskUpdate",
    "UnavailabilityInsert": "UnavailabilityInsert",
    "UnavailabilityUpdate": "UnavailabilityUpdate"
  },
  "OneOrMoreCustomers": {
    "OneCustomer": "OneCustomer",
    "MoreCustomer": "MoreCustomer"
  },
  "OneOrMoreResources": {
    "OneResource": "OneResource",
    "MoreResource": "MoreResource"
  },
  "RecurrenceDaily": {
    "AllThe": "AllThe",
    "AllWorkingDays": "AllWorkingDays"
  },
  "RecurrenceMonthly": {
    "Date": "Date",
    "Day": "Day"
  },
  "RecurrenceMonthlyDayWhich": {
    "First": "First",
    "Second": "Second",
    "Third": "Third",
    "Fourth": "Fourth",
    "Last": "Last"
  },
  "RecurrenceRange": {
    "NoEndDate": "NoEndDate",
    "EndThe": "EndThe"
  },
  "RecurrenceType": {
    "Daily": "Daily",
    "Weekly": "Weekly",
    "Monthly": "Monthly",
    "Yearly": "Yearly"
  },
  "ResourceType": {
    "Human": "Human",
    "Material": "Material",
    "ToPlan": "ToPlan",
    "Extern": "Extern"
  },
  "StatusType": {
    "Task": "Task",
    "Unavailability": "Unavailability"
  },
  "SyncType": {
    "_Google": "_Google",
    "Microsoft": "Microsoft",
    "Google": "Google"
  },
  "TaskType": {
    "Default": "Default",
    "Duration": "Duration",
    "Time": "Time"
  },
  "Title": {
    "Miss": "Miss",
    "Mr": "Mr",
    "Ms": "Ms"
  },
  "TimeLapseUnit": {
    "Day": "Day",
    "Week": "Week",
    "Month": "Month",
    "Year": "Year"
  },
  "TypeHatch": {
    "BDIAGONAL": "BDIAGONAL",
    "CROSS": "CROSS",
    "DIAGCROSS": "DIAGCROSS",
    "FDIAGONAL": "FDIAGONAL",
    "HORIZONTAL": "HORIZONTAL",
    "VERTICAL": "VERTICAL"
  },
  "WorkCapacity": {
    "Hours": "Hours",
    "Slots": "Slots"
  }
},
...

e) Antwortsprache

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

Accept-Language: de

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

2/ Beispiele für API-Aufrufe

In den folgenden Beispielen wird der verwendete Anwendungsschlüssel mit "your_key" und das Berechtigungstoken mit "your_token" notiert. 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"
        }
      }
    ]
  ]
}