Tutorial
チュートリアル

はじめに

Yappli CRM Open APIでは、Yappli CRM内の顧客情報の取得をはじめ、登録・更新など、Yappli CRMの様々な機能を使うことができます。
今後もご利用いただける機能を拡張してまいります。

API利用の申し込み

Yappli CRM Open APIをご利用いただく際は、Yappli-CRMのご契約が必要です。
ご契約の際、Yappli CRM Open API利用の旨を、弊社営業までご連絡ください。

その後、弊社からは以下をご連絡いたします。
・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" \
     -H "Content-Type: application/json" \
     -d '{
         "grant_type": "client_credentials",
         "client_id": "{client_id}",
         "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" \
     -H "Content-Type: application/json" \
     -d '{
         "login_id": "taro@crm.yapp.li",
         "password": "pass1234",
         "rank": "regular",
         "column01": "ヤプリ太郎",
         "column02": "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" \
     -H "Content-Type: application/json" \
     -d '{
         "login_id": "taro@crm.yapp.li",
         "password": "pass1234",
         "rank": "regular",
         "column01": "ヤプリ太郎",
         "column02": "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" \
     -H "Content-Type: application/json" \
     -d '{
         "point": 100,
         "title": "キャンペーンポイント10pt",
         "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" \
     -H "Content-Type: application/json" \
     -d '{
         "amount": 100,
         "title": "キャンペーンポイント10pt",
         "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に含まれています。