PlanningPME API - 開発者向けドキュメント
スケジュールのデータを他の情報システムと相互接続します。
PlanningPMEを使用すると、専用のAPIを介してデータベースへの読み取りおよび書き込みアクセスが可能になります。
PlanningPME APIは、同期と統合の簡単なプログラミングのために、現在の開発標準（REST実装とJSON形式のデータトランスポート）に従います。
このドキュメントでは、以下についての情報を提供します：
PlanningPME APIアドレスを決定する方法は？対話型ドキュメントはどこにありますか？
PlanningPME APIでセキュリティをどのように実装しますか？
PlanningPME APIでの一般的なデータの考慮事項は何ですか？
PlanningPME APIに最初のリクエストを行う方法は？
PlanningPME APIはRESTfulの原則に基づいており、デフォルトのデータ転送形式はJSONです。
このドキュメントは主に開発者向けです。以下のコンテンツをお読みいただく前に、JSON REST APIプログラミングを理解していただくことをお勧めいたします。
専用URL
各PlanningPMEクライアントには、専用のAPIアドレスがあります。
ブランド名が「MyCompany」であるとすると、APIアドレスを作成するために、おそらくブランドキー「mycompany」（大文字と小文字を区別しない）を使用する必要があります。
このキーは、このドキュメントの残りの部分で「your_brand」と表記されます。
ブランドのベースAPIアドレスは常に次のようになります：
https://api.planningpme.com/your_brand/
または
https://try.planningpme.com/your_brand/
対話型ドキュメント
各ブランドAPIは、PlanningPME APIメソッドとモデルを発見し、API呼び出しを構築するのに非常に役立つインタラクティブなドキュメントも提供します。
このドキュメントは、次のアドレスで入手できます：
https://api.planningpme.com/your_brand/doc/index
または
https://try.planningpme.com/your_brand/doc/index
これらの2つのアドレスは、アプリケーションキーの提示なしでは呼び出すことができません。
注: API でアカウント認証が有効になっている場合、PlanningPME アカウント アプリケーション内でワンクリックでインタラクティブ ドキュメントにアクセスできます。
セキュリティー
1 /アプリケーションキーについて
API へのアクセスには、アプリケーションを識別し、そのアクセスを保護するキー(appkey) が必要です。
このappkeyは、PlanningPME アカウント (API でアカウント認証が有効になっている場合) に記載してありますが、見つからない場合は弊社のテクニカルサポートへご連絡ください。
appkeyは、専用の「X-APPKEY」ヘッダーを使用して、常にAPI呼び出しのヘッダーで送信する必要があります。
GET /your_brand/api/config HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
インタラクティブドキュメントにアクセスするには、次の例のように、appkey をアドレスパラメータとして使用します。
https://api.planningpme.com/your_brand/doc/index?appkey=e991573da5ffd4sab9b1e26bc6b64aac
2 /ユーザートークンと権限のあるユーザーなりすまし
ほとんどの API リクエストでは、データにアクセスするユーザーのプロファイルを判別し、アプリケーションで定義されているユーザーとグループのアクセス許可を尊重するために、authorization token も提示する必要があります。
このトークンは、アドレス /token でユーザーを認証するときに事前に取得され、8 時間有効です。
このアドレスに送信されるデータは、アプリケーションで選択した認証方法によって異なります。
a) 通常の認証
有効にすると、クラシック認証は ユーザー名とパスワードの投稿 によって実行されます。
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=your_username&password=your_password
b) アカウント認証
有効にすると、アカウント認証は、事前にPlanningPME アカウントアプリケーションで取得した サービスアカウントトークンの投稿によって実行されます。
ここに一覧表示されているユーザーごとに、サービス アカウント トークンをクリップボードにコピーできます。
次に、コピーしたアカウントトークン(アサーション)を投稿して、APIから認証トークンを取得します。
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) OAuth クライアント認証
パートナーまたはサードパーティアプリケーションにAPI を開くには、OAuth クライアントを作成し、認証トークンを設定することをお勧めします。
管理者はOAuthアクセスをAPIで管理、または「ツール」 >「 オプション」>「OAuth」画面から管理することもできます。
OAuth クライアントID とトークンを所有すると、サードパーティはAPI で認証し、次のように認証トークンを取得できます。
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&client_id=id_of_client&assertion=token_of_client
d) 認可トークンの使用
認証が成功した場合、応答本文には次のようにJSONエレメントが含まれます。
{
"access_token": "KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_...3Is0gcH",
"token_type": "bearer",
"expires_in": 86399,
"username": "your_username"
}
"access_token" プロパティには、API 認証トークンが含まれています。
また、"token_type" プロパティで示されているように、このトークンは "bearer" 型です。したがって、承認を必要とするリクエストには、次の例のように、"Authorization" ヘッダーに値 "Bearer" が必要です。
POST /your_brand/api/customer HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac Authorization: Bearer KTuZYDLG2qjUMqMVXDuiP9giFbqDXstESvpUWzBFLpkfdlMiB3PD5s2K7En-3o39u56hpr_DlyjEc_...3Is0gcH
APIの使用法
1 /一般的なデータの考慮事項
a）モデル
PlanningPMEデータモデルの詳細は、APIのインタラクティブドキュメントでご説明しております。
b）日付形式
APIで使用され、各JSONリクエストで予期される日付形式は ISO8601形式です。 Ex:
2018-01-25T18:05:00Z
c）リストの並べ替え
GETメソッドは、多くの場合、「sortInfo」パラメータを使用して、返される完全な/ページ付けされたリストの並べ替え順序を設定します。
この情報は、プロパティの名前の直後に+または-記号が続く形式で構成されます。
たとえば、「label+」を使用して、「label」プロパティを昇順で並べ替えます。
複数の注文を追加して組み合わせることができます。
たとえば、「notValid-label+」を使用して、「notValid」プロパティを降順で並べ替え、次に「label」プロパティを昇順で並べ替えます。
プロパティラベルでは大文字と小文字が区別されることに注意してください。
d）一定の列挙
APIバージョンで使用されている列挙型の完全なリストは、「/api/config」メソッドを呼び出すことで取得されます。このリストは、将来の追加を除いて変更する権利を付与するものではありません。
GET /your_brand/api/config HTTP/1.1 Host: api.planningpme.com X-APPKEY: e991573da5ffd4sab9b1e26bc6b64aac
列挙定数の一覧を以下に示します。 - v4.7.0.28
{
...
"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",
"DoSearch": "DoSearch",
"SwitchLabel": "SwitchLabel",
"OAuthClients": "OAuthClients",
"Buttoned": "Buttoned"
},
"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",
"SAR": "SAR"
},
"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",
"Multi": "Multi",
"Location": "Location"
},
"DescriptionFieldType": {
"Index1": "Index1",
"Index2": "Index2",
"EmailBody": "EmailBody",
"Label": "Label",
"Mobile": "Mobile",
"CalendarBody": "CalendarBody",
"EmailSubject": "EmailSubject",
"Tooltip": "Tooltip",
"LabelAssignment": "LabelAssignment",
"CalendarSubject": "CalendarSubject",
"Print": "Print",
"ToPlan": "ToPlan",
"LabelUnavailability": "LabelUnavailability",
"PrintUnavailability": "PrintUnavailability",
"HeaderCustomer": "HeaderCustomer",
"CaptionCustomer": "CaptionCustomer",
"HeaderProject": "HeaderProject",
"CaptionProject": "CaptionProject",
"HeaderResource": "HeaderResource",
"CaptionEquipment": "CaptionEquipment"
},
"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",
"Unavailability0": "Unavailability0",
"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",
"Unavailability": "Unavailability"
},
"DoMode": {
"None": "None",
"End": "End",
"Duration": "Duration"
},
"EffActionType": {
"Email": "Email",
"Sms": "Sms",
"MicrosoftOutlook": "MicrosoftOutlook",
"GoogleCalendar": "GoogleCalendar"
},
"EffGapUnit": {
"Minute": "Minute",
"Hour": "Hour",
"Day": "Day",
"Week": "Week",
"Month": "Month",
"Year": "Year"
},
"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",
"Creator": "Creator"
},
"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",
"User": "User",
"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",
"Lucca": "Lucca"
},
"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）応答言語
エラーメッセージなどの応答テキストで使用される言語は、「Accept-Language」ヘッダーで指定できます。
Accept-Language: 英語
PlanningPME API および PlanningPME WebAccess で使用できる言語は、デンマーク語、オランダ語、フランス語 (fr)、ドイツ語、イタリア語 (it)、日本語 (ja)、ノルウェー語 (no)、ポーランド語 (pl)、ポルトガル語 (pt)、ロシア語 (ru)、スペイン語 (de)、スウェーデン語 (sv) です。
2 / API呼び出しの例
以下の例では、使用されるアプリケーションキーは"your_key"と示され、認証トークンは"your_token"と示されています。それらを独自の値に置き換えてください。
/api/task
→ GET "/api/task"メソッドを使用して、タスクの完全なリストまたはページ付けされたリストを取得します。
GET /your_brand/api/task?pageIndex=1&pageSize=20&sortInfo=label+ HTTP/1.1 Host: api.planningpme.com X-APPKEY: your_key Authorization: Bearer your_token
ラベルの降順で並べ替えられた20個のタスクの2ページ目を含むタスクの配列を返します。
{
"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"
}
}
]
}
→ GET "/api/task/{id}"メソッドを使用して詳細なタスクを取得します。
GET /your_brand/api/task/756 HTTP/1.1 Host: api.planningpme.com X-APPKEY: votre_clé Authorization: Bearer your_token
ID756のタスクの詳細なタスクオブジェクト表現を返します。
{
"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"
}
}
]
]
}
/api/oauth
→ GET メソッド"/api/oauth/client" でOAuth クライアントのリストを取得します。
GET /your_brand/api/oauth/client HTTP/1.1 Host: api.planningpme.com X-APPKEY: your_key Authorization: Bearer your_token
{
"totalItems": 2,
"items": [
{
"id": "2bc87bded6bf4de7babe8ea5a9452735",
"name": "backoffice"
},
{
"id": "1601c39ed33a4c4084750356a7f8d7a5",
"name": "apptest2"
}
]
}
→ "/api/oauth/client" POST メソッドを使用して、新しいOAuth クライアントを作成します。
POST /your_brand/api/oauth/client HTTP/1.1
Host: api.planningpme.com
X-APPKEY: votre_clé
Authorization: Bearer your_token
{
"name": "apptest3"
}
作成されたクライアントとそのID を返します。
{
"id": "22f37990d2304af3a9e20dc4b05efe26",
"name": "apptest3"
}
→ POST メソッド"/api/oauth/token" を使用して、特定のクライアント(ここでは"apptest3") と特定のユーザー(ここではキーが99 のユーザー) の新しいOAuth トークンを作成します。
POST /your_brand/api/oauth/token HTTP/1.1
Host: api.planningpme.com
X-APPKEY: votre_clé
Authorization: Bearer your_token
{
"clientId": "22f37990d2304af3a9e20dc4b05efe26",
"user": {
"key": 99
}
}
作成されたトークン、有効期限、および関連するアサーションを返します。
完全なアサーション(プロパティ"jwt") は取得できなくなりますのでご注意ください。 そのため、作成されたらすぐに安全な場所に保存することをお勧めします。
{
"id": "63d134cf760940e7af7acf16e4890835",
"userKey": 99,
"expirationDate": "2027-05-14T13:11:49.8116664Z",
"resume": "eyJhbGciOiJodHR...wtO_PkdOFllvyNk",
"invalid": false,
"jwt": "eyJhbGciOiJodHRwOi8vd3d3FgdfLm9yZy8yMDAxLzA0L3htbGRzaWctbW9yZSNobWFjLXNoYTI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwidW5pcXVlX25hbWUiOiI2M2QxMzRjZjc2MDk0MGU3YWY3YWNmMTZlODk1MDgzNSIsImp0aSI6ImRkOGM0OTZlLTBlZjYtNDQ5MS04MGNkLTM1YzRkODIxMGZlZSIsImlhdCI6MTc0NzIlkj345SwibmJmIjoxNzQ3MjI4MzA5LCJleHAiOjE4MTAzMDAzMDksImlzcyI6Imh0dHBzOi8vYXBpLnBsYW5uaW5ncG1lLmNvbSIsImF1ZCI6IjMzZjM3OTkwZDIzMDRhZjNhOWUyMGRjNGIwNWVmZTI2In0.9f-X_bc4Ca8gTyQ_FZJsAvdH0gkWwtO_PkdOFllvyNk"
}
→ GET メソッド"/api/oauth/token?clientID={id}" でOAuth クライアントにリンクされているトークンのリストを取得します。
GET /your_brand/api/oauth/token?clientId=2bc87bded6bf4de7babe8ea5a9212735 HTTP/1.1 Host: api.planningpme.com X-APPKEY: your_key Authorization: Bearer your_token
{
"totalItems": 1,
"items": [
{
"id": "63d134cf760940e7af7acf16e4890835",
"userKey": 99,
"expirationDate": "2027-05-14T13:11:49.8116664Z",
"resume": "eyJhbGciOiJodHR...wtO_PkdOFllvyNk",
"invalid": false
}
]
}