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.
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.
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" } } ] ] }