APIバージョン3の利用方法(カスタマー新規登録・更新・削除)

注意事項

外部フォームからSATORIへカスタマー登録をするための目的で公開しているAPIです。
大量なリクエストを必要とするようなカスタマー情報の同期など、意図しない目的でのご利用はご遠慮ください。

 

また、カレント以外のバージョンは非推奨になっています。

 

前提事項

バージョン3では以下の3種類のAPIが提供されます。

  • 新規登録用: registration.json
  • 新規登録および更新用: upsert.json
  • 削除用: delete.json

それぞれ、サンプルを元に解説します。

バージョン3では、任意のパラメータを送付することができ、その内容を管理画面からご確認いただくことが可能です。詳細はこのページ下部の「管理画面での確認」項目をご確認ください。

 

管理画面から取得する項目

下記の項目は管理画面より取得してください。

  • user_key: 'ユーザーアクセスキー', #(管理画面より取得)
  • user_secret: 'ユーザーシークレットキー', #(管理画面より取得)
  • company_key: 'カンパニーアクセスキー', #(管理画面より取得)
  • company_secret: 'カンパニーシークレットキー', #(管理画面より取得)

取得方法はこちらをご参照ください。

 


新規登録用: registration.json

registration.json での更新可能項目

  • タグの追加
  • メール配信可否、スター、ステータスの変更
  • 空欄項目への追加(既に登録がある場合、更新できません) 

リクエストについて

  • Content-Type: application/x-www-form-urlencoded
  • 文字コード: UTF-8
  • APIのURL: https://api.satr.jp/api/v3/public/customer/registration.json
  • 送信するパラメータリスト
パラメータ名 日本語名 必須 備考
user_key ユーザー
アクセスキー
管理画面より取得
user_secret ユーザー
シークレットキー
管理画面より取得
company_key カンパニー
アクセスキー
管理画面より取得
company_secret カンパニー
シークレットキー
管理画面より取得
customer[identity_type] 識別タイプ 新規登録用は「email」のみ指定可
customer[email] メールアドレス 最大255文字
(メールアドレスとして適切な文字列で半角のみ)
customer[last_name] 苗字 - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[first_name] 名前 - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[last_name_reading] 苗字(ふりがな) - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[first_name_reading] 名前(ふりがな) - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[lead_company_name] 会社 - 最大255文字 (例: SATORI株式会社)
customer[department] 部署 - 最大255文字 (例: マーケティング部)
customer[position] 役職 - 最大255文字 (例: 部長)
customer[phone_number] 電話番号 - 最大255文字 (例: 03-1234-5678)
customer[mobile_phone_number] 携帯電話番号 - 最大255文字 (例: 090-1234-5678)
customer[web_site] WEBサイト - 最大255文字 (例: https://satori.marketing)
customer[address] 住所 - 最大255文字 (例: 東京都渋谷区道玄坂)
customer[collection_route] 情報獲得経路 最大255文字 (例: 問合せフォーム)
customer[collection_date] 情報獲得日 - 日付形式文字列: yyyy-MM-dd HH:mm:ss
customer[delivery_permission] メール配信可否 - 設定可能な値
・approval (許可)
・reject (拒否)
customer[star] スター - 設定可能な値
・true
・false
customer[status] ステータス - 設定可能な値
・regist (未対応)
・reply (返信済)
・phone (電話済)
・visit (訪問済)
・contract (契約済)
・lost (失注)
customer[append_tags] タグ - 最大255文字
カンマ区切りタグを複数指定可能
"(" ")" "AND" "NOT" "OR" を含まない文字列
(例: メルマガ登録, サイト訪問者)
customer[memo] メモ - 最大500文字

 

cURLリクエストサンプル

curl -X POST \
     -d "user_key=<ユーザーアクセスキー>" \
     -d "user_secret=<ユーザーシークレットキー>" \
     -d "company_key=<カンパニーアクセスキー>" \
     -d "company_secret=<カンパニーシークレットキー>" \
     -d "customer[identity_type]=email" \
     -d "customer[email]=<メールアドレス>" \
     -d "customer[collection_route]=<情報獲得経路>" \
     https://api.satr.jp/api/v3/public/customer/registration.json




新規登録および更新用: upsert.json

upsert.json の動作

指定したemailまたはhashcodeが存在していない場合には新規登録、存在している場合は更新になります。

リクエストについて

  • Content-Type: application/x-www-form-urlencoded
  • 文字コード: UTF-8
  • APIのURL: https://satr.jp/api/v3/public/customer/upsert.json
  • 送信するパラメータリスト
パラメータ名 日本語名 必須 備考
user_key ユーザー
アクセスキー
管理画面より取得
user_secret ユーザー
シークレットキー
管理画面より取得
company_key カンパニー
アクセスキー
管理画面より取得
company_secret カンパニー
シークレットキー
管理画面より取得
customer[identity_type] 識別タイプ 更新用は「email」または「hashcode」を指定可
レスポンスで取得できるcustomer[hashcode]で更新を行いたい場合は「hashcode」を指定
customer[email] メールアドレス 最大255文字
(メールアドレスとして適切な文字列で半角のみ)
customer[hashcode] ハッシュコード - identity_typeでhashcodeを指定した場合は必須
emailの代わりにカスタマーを識別するキーとなります
customer[last_name] 苗字 - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[first_name] 名前 - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[last_name_reading] 苗字(ふりがな) - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[first_name_reading] 名前(ふりがな) - 最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
customer[lead_company_name] 会社 - 最大255文字 (例: SATORI株式会社)
customer[department] 部署 - 最大255文字 (例: マーケティング部)
customer[position] 役職 - 最大255文字 (例: 部長)
customer[phone_number] 電話番号 - 最大255文字 (例: 03-1234-5678)
customer[mobile_phone_number] 携帯電話番号 - 最大255文字 (例: 090-1234-5678)
customer[web_site] WEBサイト - 最大255文字 (例: https://satori.marketing)
customer[address] 住所 - 最大255文字 (例: 東京都渋谷区道玄坂)
customer[collection_route] 情報獲得経路 最大255文字 (例: 問合せフォーム)
customer[collection_date] 情報獲得日 - 日付形式文字列: yyyy-MM-dd HH:mm:ss
customer[delivery_permission] メール配信可否 - 設定可能な値
・approval (許可)
・reject (拒否)
customer[star] スター - 設定可能な値
・true
・false
customer[status] ステータス - 設定可能な値
・regist (未対応)
・reply (返信済)
・phone (電話済)
・visit (訪問済)
・contract (契約済)
・lost (失注)
customer[append_tags] タグ - 最大255文字
カンマ区切りタグを複数指定可能
"(" ")" "AND" "NOT" "OR" を含まない文字列
(例: メルマガ登録, サイト訪問者)
customer[memo] メモ - 最大500文字

cURLリクエストサンプル

curl -X POST \
     -d "user_key=<ユーザーアクセスキー>" \
     -d "user_secret=<ユーザーシークレットキー>" \
     -d "company_key=<カンパニーアクセスキー>" \
     -d "company_secret=<カンパニーシークレットキー>" \
     -d "customer[identity_type]=email" \
     -d "customer[email]=<メールアドレス>" \
     -d "customer[collection_route]=<情報獲得経路>" \
     https://api.satr.jp/api/v3/public/customer/upsert.json




削除用: delete.json

registration.json の動作

指定したemailまたはhashcodeのカスタマーが削除されます。

リクエストについて

  • Content-Type: application/x-www-form-urlencoded
  • 文字コード: UTF-8
  • APIのURL: https://satr.jp/api/v3/public/customer/delete.json
  • 送信するパラメータリスト
パラメータ名 日本語名 必須 備考
user_key ユーザー
アクセスキー
管理画面より取得
user_secret ユーザー
シークレットキー
管理画面より取得
company_key カンパニー
アクセスキー
管理画面より取得
company_secret カンパニー
シークレットキー
管理画面より取得
customer[identity_type] 識別タイプ 更新用は「email」または「hashcode」を指定可
レスポンスで取得できるcustomer[hashcode]で更新を行いたい場合は「hashcode」を指定します
customer[email] メールアドレス 最大255文字
(メールアドレスとして適切な文字列で半角のみ)
customer[hashcode] ハッシュコード - identity_typeでhashcodeを指定した場合は必須
emailの代わりにカスタマーを識別するキーとなります

cURLリクエストサンプル

curl -X POST \
     -d "user_key=<ユーザーアクセスキー>" \
     -d "user_secret=<ユーザーシークレットキー>" \
     -d "company_key=<カンパニーアクセスキー>" \
     -d "company_secret=<カンパニーシークレットキー>" \
     -d "customer[identity_type]=email" \
     -d "customer[email]=<メールアドレス>" \
     https://api.satr.jp/api/v3/public/customer/delete.json




 

レスポンスについて

JSONフォーマットでレスポンスが返されます。
レスポンスは以下の種類があります。


  成功
  {"status":200, "message": {"customer[hashcode]": "8eced811cdb57f56"}}
  メールアドレスに対応したハッシュコードが返却されます。

  失敗(苗字なし)
  {"status":400, "message": "バリデーションに失敗しました。 苗字を入力してください。"}

  失敗(メールアドレスなし)
  {"status": 400, "message": "validation error: customer[email] required."}

  失敗(APIキー不正)
  {"status":401, "message": "Unauthorized"}

  失敗(その他)
  {"status": 409, "message": "Conflict"}

 


 

レスポンスの処理

成功した場合には次のいずれかの処理を追加することで、登録されたメールアドレスとブラウザ(Cookie)とを紐付けることができます。

  レスポンス内容 => {"status": 200, "message": {"customer[hashcode]": "8eced811cdb57f56"}}


・紐付け方法1
  返却されたhashcodeに-00を追加した値を、遷移先ページのcパラメータとして追加してください。
遷移先ページにデータ取得タグが設置されている必要があります。

例:(会員登録完了のサンクスページを以下のようにしてください。) http://sample.com/thank_you?c=8eced811cdb57f56-00

・紐付け方法2
  返却されたhashcodeに-00を追加した値を使用して、遷移先ページに以下のJavaScriptを追加してください。
scriptタグ設置場所はデータ取得タグの上になります。

<script>
var StDmp = {};
StDmp.additionalParams = { c: "8eced811cdb57f56-00" };
</script>

管理画面での確認

APIバージョン3では、登録または更新成功した場合、送信した内容を管理画面から確認することができます。

登録または更新を行ったカスタマー詳細画面の最新アクション一覧から、アクションが「API登録」になっているものの「内容」部分のリンクに遷移いただくことで、以下のように、送信内容を確認することができます。

 

apiregis.png