Tutorial
チュートリアル
はじめに
Yappli CRM Open APIでは、Yappli CRM内の顧客情報の取得をはじめ、登録・更新など、Yappli CRMの様々な機能を使うことができます。
今後もご利用いただける機能を拡張してまいります。
API利用の申し込み
Yappli CRM Open APIをご利用いただく際は、Yappli-CRMのご契約が必要です。
ご契約の際、Yappli CRM Open API利用の旨、ならびにAPIへアクセスするサーバーの"IPアドレス"を、弊社営業までご連絡ください。
その後、弊社からは以下をご連絡いたします。
・client_id (後述の"認証"で利用します)
・client_secret (後述の"認証"で利用します)
・Yappli CRMのログインアカウント
リクエスト
Yappli CRM Open API へのリクエストの文字エンコーディングはUTF-8のみに対応しています。
リクエストを行う際にHTTPリクエストのUser-Agentヘッダーを設定してください。
レスポンス
Yappli CRM Open API のレスポンスはJSONオブジェクトを返しています。 文字エンコーディングはUTF-8です。
認証
Yappli CRM API は、OAuth 2.0のクライアント・クレデンシャルズフローの仕様に準拠しています。
RFC 6749, 4.4. [Client Credentials Grant]で定義されているフローとなります。
トークンエンドポイントにトークンリクエストを投げ、応答としてアクセストークンを受け取るフローです。
このフローでは、クライアントアプリケーションの認証のみがおこなわれます。
アクセストークンの取得
弊社から送付されたclient_id、及びログイン情報を使用し、アクセストークンを取得してください。有効期間が過ぎた場合、再度アクセストークンを取得してください。
リクエスト
POST {{APP_URL}}/api/ext/token
アクセストークンの作成
# Example Request
curl -X POST "{{APP_URL}}/api/ext/token" \
-d grant_type=client_credentials \
-d client_id={client_id} \
-d client_secret={client_secret}
# Example Response
{
"access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"token_type": "bearer",
"refresh_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"expires_in": 86400,
"scope": null
}
API の利用にはアクセストークンが必要です。 Example Requestを参考にアクセストークンの作成を行なってください。
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
grant_type* | String | client_credentials | - |
client_id* | String | OAuthアプリケーションのクライアントID | - |
client_secret* | String | OAuthアプリケーションのクライアントシークレット | - |
レスポンス(成功時)
Property | Type | Description |
---|---|---|
access_token | String | アクセストークン |
token_type | String | アクセストークンの種類 |
expires_in | String | アクセストークンの有効期限(秒) |
scope | String | ---- |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
アクセストークンの再発行
アクセストークンの有効期間は発行から1日間です。期限が過ぎると、そのアクセストークンではAPIを利用することができなくなります。その場合は、再度アクセストークンの取得を行ってください。
顧客
顧客一覧
登録されている顧客の一覧を取得します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
リクエスト
GET {{APP_URL}}/api/ext/users
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
per_page | Integer | 取得件数 | 50 |
page | Integer | 取得開始ページ | 1 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
members | Array | オブジェクトの配列 |
members > member | Array[Member Object] | 顧客オブジェクトの配列 |
members > member > id | String | YappliCRMの顧客ID |
members > member > unique_id | String | お客様のシステムでユニークなID |
members > member > login_id | String | ログインID |
members > member > rank | String | ランク |
members > member > column01 〜 column50 | String | カスタムフィールド |
members > member > secret_quetion | String | 秘密の質問 |
members > member > secret_answer | String | 秘密の質問の答え |
members > member > point | Integer | 保有ポイント |
members > member > total_point | Integer | 総取得ポイント |
members > member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
members > member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
members > member > memo | String | メモ |
members > member > point_geted_at | Date | ポイント最終取得日 |
members > member > point_used_at | Date | ポイント最終使用日 |
members > member > point_expired_at | Integer | 最短ポイント有効期限日 |
members > member > point_expired_point | Date | 最短有効期限切れになるポイント数 |
members > member > logined_at | Date | 最終ログイン日 |
members > member > created_at | Date | 登録日 |
members > member > updated_at | Date | 更新日 |
total | Integer | 総数 |
per_page | Integer | 取得件数 |
current_page | Integer | 現在のページ番号 |
last_page | Integer | 最後のページのページ番号 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
顧客詳細
登録されている顧客の詳細情報を取得します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
リクエスト
GET {{APP_URL}}/api/ext/users/{id}
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
Id* | String | 会員ID | - |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
member | Array[Member Object] | 顧客オブジェクトの配列 |
member > id | String | YappliCRMの顧客ID |
member > unique_id | String | お客様のシステムでユニークなID |
member > login_id | String | ログインID |
member > rank | String | ランク |
member > column01 〜 column50 | String | カスタムフィールド |
member > secret_quetion | String | 秘密の質問 |
member > secret_answer | Integer | 秘密の質問の答え |
member > point | Integer | ポイント |
member > total_point | Integer | 総取得ポイント |
member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
member > memo | String | メモ |
member > point_geted_at | Date | ポイント最終取得日 |
member > point_used_at | Date | ポイント最終使用日 |
member > point_expired_at | Date | 最短ポイント有効期限日 |
member > point_expired_point | Integer | 最短有効期限切れになるポイント数 |
member > logined_at | Date | 最終ログイン日 |
member > created_at | Date | 登録日 |
member > updated_at | Date | 更新日 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
顧客詳細(ユニークID)
登録されている顧客の詳細情報をユニークIDで取得します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
リクエスト
GET {{APP_URL}}/api/ext/users/unique_id/{unique_id}
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
unique_id* | String | お客様のシステムでユニークなID | - |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
member | Array[Member Object] | 顧客オブジェクトの配列 |
member > id | String | YappliCRMの顧客ID |
member > unique_id | String | お客様のシステムでユニークなID |
member > login_id | String | ログインID |
member > rank | String | ランク |
member > column01 〜 column50 | String | カスタムフィールド |
member > secret_quetion | String | 秘密の質問 |
member > secret_answer | Integer | 秘密の質問の答え |
member > point | Integer | ポイント |
member > total_point | Integer | 総取得ポイント |
member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
member > memo | String | メモ |
member > point_geted_at | Date | ポイント最終取得日 |
member > point_used_at | Date | ポイント最終使用日 |
member > point_expired_at | Date | 最短ポイント有効期限日 |
member > point_expired_point | Integer | 最短有効期限切れになるポイント数 |
member > logined_at | Date | 最終ログイン日 |
member > created_at | Date | 登録日 |
member > updated_at | Date | 更新日 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
顧客登録
新規顧客情報を登録します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
リクエスト
POST {{APP_URL}}/api/ext/users
# Example Request
curl -X POST "{APP_URL}/api/ext/users" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-F login_id=taro@crm.yapp.li \
-F password=pass1234 \
-F rank=regular \
-F column01='ヤプリ太郎' \
-F colmun02='2000-12-31'
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
unique_id* | String | お客様のシステムでユニークなID | |
login_id | String | ログインID | |
password | String | パスワード | |
rank | String | ランク | |
column01 〜 column50 | String | カスタムフィールド | |
secret_question | String | 秘密の質問 | |
secret_answer | String | 秘密の質問の答え | |
logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
|
enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
|
logined_at | Date | 最終ログイン日 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
member | Array[Member Object] | 顧客オブジェクトの配列 |
member > id | String | YappliCRMの顧客ID |
member > unique_id | String | お客様のシステムでユニークなID |
member > login_id | String | ログインID |
member > rank | String | ランク |
member > column01 〜 column50 | String | カスタムフィールド |
member > secret_quetion | String | 秘密の質問 |
member > secret_answer | Integer | 秘密の質問の答え |
member > point | Integer | ポイント |
member > total_point | Integer | 総取得ポイント |
member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
member > memo | String | メモ |
member > point_geted_at | Date | ポイント最終取得日 |
member > point_used_at | Date | ポイント最終使用日 |
member > point_expired_at | Date | 最短ポイント有効期限日 |
member > point_expired_point | Integer | 最短有効期限切れになるポイント数 |
member > logined_at | Date | 最終ログイン日 |
member > created_at | Date | 登録日 |
member > updated_at | Date | 更新日 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
顧客更新
登録されている顧客の情報を更新します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
HTTP リクエスト
PUT {{APP_URL}}/api/ext/users/{id}
# Example Request
curl -X PUT "{APP_URL}/api/ext/users/{id}" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-F login_id=taro@crm.yapp.li \
-F password=pass1234 \
-F rank=regular \
-F column01='ヤプリ太郎' \
-F colmun02='2000-12-31'
パラメータ (* 必須)
HTTP STATUS CODE: 200
Parameter | Type | Description | Default |
---|---|---|---|
id* | String | YappliCRMの顧客ID | |
login_id | String | ログインID | |
password | String | パスワード | |
rank | String | ランク | |
column01 〜 column50 | String | カスタムフィールド | |
secret_question | String | 秘密の質問 | |
secret_answer | String | 秘密の質問の答え | |
logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
|
enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
|
logined_at | Date | 最終ログイン日 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
member | Array[Member Object] | 顧客オブジェクトの配列 |
member > id | String | YappliCRMの顧客ID |
member > unique_id | String | お客様のシステムでユニークなID |
member > login_id | String | ログインID |
member > rank | String | ランク |
member > column01 〜 column50 | String | カスタムフィールド |
member > secret_quetion | String | 秘密の質問 |
member > secret_answer | Integer | 秘密の質問の答え |
member > point | Integer | ポイント |
member > total_point | Integer | 総取得ポイント |
member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
member > memo | String | メモ |
member > point_geted_at | Date | ポイント最終取得日 |
member > point_used_at | Date | ポイント最終使用日 |
member > point_expired_at | Date | 最短ポイント有効期限日 |
member > point_expired_point | Integer | 最短有効期限切れになるポイント数 |
member > logined_at | Date | 最終ログイン日 |
member > created_at | Date | 登録日 |
member > updated_at | Date | 更新日 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
ポイント
ポイント付与履歴
顧客に対して付与したポイントの履歴を取得します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
HTTP リクエスト
GET {{APP_URL}}/api/ext/users/{id}/points
# Example Request
curl -X GET "{APP_URL}/api/ext/users/{id}/points" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
per_page | Integer | 取得件数 | 50 |
page | Integer | 取得開始ページ | 1 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
points | Array | オブジェクトの配列 |
points > point | Array[Point Object] | ポイントオブジェクトの配列 |
points > point > id | String | ポイントの付与ID |
points > point > title | String | 付与理由 |
points > point > point | Integer | 付与ポイント数 |
points > point > remarks | String | 備考欄 |
points > point > expired_at | Date | ポイント有効期限 |
points > point > created_at | Date | 登録日 |
points > point > updated_at | Date | 更新日 |
total | Integer | 総数 |
per_page | Integer | 取得件数 |
current_page | Integer | 現在のページ番号 |
last_page | Integer | 最後のページのページ番号 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
ポイント有効期限一覧
顧客に対して付与したポイントの消滅する日時を有効期限日ごとに集計した情報を取得します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
HTTP リクエスト
GET {{APP_URL}}/api/ext/users/{id}/points/expired_list
# Example Request
curl -X GET "{APP_URL}/api/ext/users/{id}/points/expired_list" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
per_page | Integer | 取得件数 | 50 |
page | Integer | 取得開始ページ | 1 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
points | Array | オブジェクトの配列 |
points > point | Array[Point Object] | ポイントオブジェクトの配列 |
points > point > expired_at | Date | ポイント有効期限 |
points > point > point | Integer | 消滅ポイント数 |
total | Integer | 総数 |
per_page | Integer | 取得件数 |
current_page | Integer | 現在のページ番号 |
last_page | Integer | 最後のページのページ番号 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
ポイント付与(加算・減算)
ポイントの付与(加算・減算)を行います。
プラス値は加算、マイナス値は減算になります。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
HTTP リクエスト
POST {{APP_URL}}/api/ext/users/{id}/points
# Example Request
curl -X POST "{APP_URL}/api/ext/users/{id}/points" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-F point=100 \
-F title='キャンペーンポイント10pt,' \
-F remarks='備考欄'
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
point * | Integer | 付与ポイント数(マイナス値だと減算になります。) | |
title | String | 付与理由 | |
expired_at | Date | ポイント有効期限 (YYYY-MM-DD) ※減算の場合は未指定 ※未指定の場合は、デフォルト設定に従います。 |
|
remarks | String | 備考欄 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
member | Array[Member Object] | 顧客オブジェクトの配列 |
member > id | String | YappliCRMの顧客ID |
member > unique_id | String | お客様のシステムでユニークなID |
member > login_id | String | ログインID |
member > rank | String | ランク |
member > column01 〜 column50 | String | カスタムフィールド |
member > secret_quetion | String | 秘密の質問 |
member > secret_answer | Integer | 秘密の質問の答え |
member > point | Integer | ポイント |
member > total_point | Integer | 総取得ポイント |
member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
member > memo | String | メモ |
member > point_geted_at | Date | ポイント最終取得日 |
member > point_used_at | Date | ポイント最終使用日 |
member > point_expired_at | Date | 最短ポイント有効期限日 |
member > point_expired_point | Integer | 最短有効期限切れになるポイント数 |
member > logined_at | Date | 最終ログイン日 |
member > created_at | Date | 登録日 |
member > updated_at | Date | 更新日 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
ポイント計算
予め設定したランク情報のポイント付与率を使用し、計算値からポイント数を計算し付与します。
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
HTTP リクエスト
POST {{APP_URL}}/api/ext/users/{id}/points/calculation
# Example Request
curl -X POST "{APP_URL}/api/ext/users/{id}/points/calculation" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-F amount=100 \
-F title='キャンペーンポイント10pt,' \
-F remarks='備考欄'
パラメータ (* 必須)
Parameter | Type | Description | Default |
---|---|---|---|
amount * | Integer | 計算値 | |
title | String | 付与理由 | |
expired_at | Date | ポイント有効期限 (YYYY-MM-DD) ※減算の場合は未指定 ※未指定の場合は、デフォルト設定に従います。 |
|
remarks | String | 備考欄 |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
member | Array[Member Object] | 顧客オブジェクトの配列 |
member > id | String | YappliCRMの顧客ID |
member > unique_id | String | お客様のシステムでユニークなID |
member > login_id | String | ログインID |
member > rank | String | ランク |
member > column01 〜 column50 | String | カスタムフィールド |
member > secret_quetion | String | 秘密の質問 |
member > secret_answer | Integer | 秘密の質問の答え |
member > point | Integer | 保有ポイント |
member > total_point | Integer | 総取得ポイント |
member > logined | Integer | ログイン状態 (0:未ログイン 1:ログイン済) |
member > enabled | Integer | 利用可/不可 (0:利用不可 1:利用可) |
member > memo | String | メモ |
member > point_geted_at | Date | ポイント最終取得日 |
member > point_used_at | Date | ポイント最終使用日 |
member > point_expired_at | Date | 最短ポイント有効期限日 |
member > point_expired_point | Integer | 最短有効期限切れになるポイント数 |
member > logined_at | Date | 最終ログイン日 |
member > created_at | Date | 登録日 |
member > updated_at | Date | 更新日 |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
サービス間のログインユーザーの引き継ぎ
Yappli-CRMと他サービス間でログインユーザーの情報を引き継ぐために発行されたトークンをチェックします。
成功すると、ログインユーザーの顧客情報を返却します。
引き継ぎトークンチェック
HTTP リクエストヘッダ
Authorization: Bearer {ACCESS_TOKEN}
HTTP リクエスト
GET {{APP_URL}}/api/ext/check/{token}?id={id}
# Example Request
curl -X GET "{APP_URL}/api/ext/check/{token}?id={id}" \
-H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
パラメータ (* 必須)
HTTP STATUS CODE: 200
Parameter | Type | Description | Default |
---|---|---|---|
token * | String | 引き継ぎトークン | Yappliから画面遷移時に受け取った引き継ぎトークン |
ID * | String | YappliCRMの顧客ID | 会員連携時にお客様側でも保管済みであること |
レスポンス(成功時)
HTTP STATUS CODE: 200
Property | Type | Description |
---|---|---|
status | Boolean | true or false |
レスポンス(失敗時)
HTTP Status Code | error | error_description |
---|---|---|
400 | Bad Request | 要求が無効です。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |
401 | Unauthorized | 認証に失敗しました。 ※エラーを説明するJSON文字列がレスポンスBODYに含まれています。 |