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

注意事項

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

 

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

 

前提事項

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

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

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

 

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

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

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

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

 


新規登録用: registration.json(サンプル

registration.json での更新可能項目

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

リクエストについて

  • 文字コード: 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', #(キーのタイプ:'email')※必須
"customer[lead_company_name]" => 'SATORI株式会社', #(会社名:varchar(255))
"customer[department]" => 'プロダクト事業部', #(部署名:varchar(255))
"customer[position]" => '事業部長', #(肩書:varchar(255))
"customer[phone_number]" => '03-0000-1111', #(電話番号:varchar(255))
"customer[mobile_phone_number]" => '080-0000-0000', #(携帯電話番号:varchar(255))
"customer[last_name]" => '山田', #(氏:varchar(255))※新規登録の場合必須
"customer[first_name]" => '太郎', #(名:varchar(255))
"customer[last_name_reading]" => 'やまだ', #(氏(ふりがな):varchar(255))
"customer[first_name_reading]" => 'たろう', #(名(ふりがな):varchar(255))
"customer[email]" => 'taro.yamada@satori.team', #(メールアドレス:varchar(255))※必須
"customer[web_site]" => 'https://satori.marketing/', #(ウェブアドレス:varchar(255))
"customer[address]" => '東京都渋谷区代々木4-29-3 西参道梅村ビル4F', #(住所:varchar(255))
"customer[collection_route]" => 'お問い合わせフォーム', #(情報獲得経路:varchar(255))※必須
"customer[collection_date]" => '2017-01-01 12:00:00', #(情報獲得日時:date)※yyyy-MM-dd HH:mm:ss
"customer[delivery_permission]" => 'approval', #(メール配信可否:enum('approval','reject')、registration.jsonで変更可能)
"customer[star]" => 'true', #(スター設定:enum('true','false'))
"customer[status]" => 'reply', #(ステータス:enum('regist', 'reply', 'phone', 'visit', 'contract'))
"customer[append_tags]" => 'タグ1,タグ2', #(タグの追加:varchar(255)のカンマ区切り *タグは追加となります)
"customer[memo]" => 'メモです。' #(メモ:text ※最大文字数は500文字です)




新規登録および更新用: upsert.json (サンプル

upsert.json の動作

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

リクエストについて

  • 文字コード: 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', #(キーのタイプ:enum('email','hashcode')、通常はemailを用いますが、レスポンスで取得できるcustomer[hashcode]で更新を行いたい場合は、'hashcode'を指定します)※必須
#"customer[hashcode]" => 'XXXXXXXXXXXXXXXX', #(customer[identity_type]で'hashcode'を指定した場合必須です。)
"customer[lead_company_name]" => 'SATORI株式会社', #(会社名:varchar(255))
"customer[department]" => 'プロダクト事業部', #(部署名:varchar(255))
"customer[position]" => '事業部長', #(肩書:varchar(255))
"customer[phone_number]" => '03-0000-1111', #(電話番号:varchar(255))
"customer[mobile_phone_number]" => '080-0000-0000', #(携帯電話番号:varchar(255))
"customer[last_name]" => '山田', #(氏:varchar(255))※新規登録の場合、必須項目です。
"customer[first_name]" => '太郎', #(名:varchar(255))
"customer[last_name_reading]" => 'やまだ', #(氏(ふりがな):varchar(255))
"customer[first_name_reading]" => 'たろう', #(名(ふりがな):varchar(255))
"customer[email]" => 'taro.yamada@satori.team', #(メールアドレス:varchar(255))※新規登録の場合、および、customer[identity_type]で'email'を指定した場合必須
"customer[web_site]" => 'https://satori.marketing/', #(ウェブアドレス:varchar(255))
"customer[address]" => '東京都渋谷区代々木4-29-3 西参道梅村ビル4F', #(住所:varchar(255))
"customer[collection_route]" => 'お問い合わせフォーム', #(情報獲得経路:varchar(255))※必須
"customer[collection_date]" => '2017-01-01 12:00:00', #(情報獲得日時:date)※yyyy-MM-dd HH:mm:ss
"customer[delivery_permission]" => 'approval', #(メール配信可否:enum('approval','reject'))
"customer[star]" => 'false', #(スター設定:enum('true','false'))
"customer[status]" => 'regist', #(ステータス:enum('regist', 'reply', 'phone', 'visit', 'contract'))
"customer[append_tags]" => 'タグ1,タグ2',  #(タグの追加:varchar(255)のカンマ区切り ※タグは置き換わらずに追加となります)
"customer[delete_tags]" => 'タグ3,タグ4',  #(タグの削除:varchar(255)のカンマ区切り ※指定したタグが存在すれば、削除されます)
"customer[memo]" => 'メモです。' #(メモ:text ※最大文字数は500文字です)




削除用: delete.json (サンプル

registration.json の動作

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

リクエストについて

  • 文字コード: 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', #(キーのタイプ:enum('email','hashcode')、通常はemailを用いますが、レスポンスで取得できるcustomer[hashcode]で更新を行いたい場合は、'hashcode'を指定します)※必須
#"customer[hashcode]" => 'XXXXXXXXXXXXXXX', # ※customer[identity_type]で'hashcode'を指定した場合必須
"customer[email]" => 'taro.yamada@satori.team', #(メールアドレス:varchar(255))※customer[identity_type]で'email'を指定した場合必須




 

レスポンスについて

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

  こちらのhashcodeに-00を追加した値を、遷移先ページのcパラメータとして追加してください。
  例:(会員登録完了のサンクスページを以下のようにしてください。)
  http://sample.com/thank_you?c=8eced811cdb57f56-00

  登録されたメールアドレスとブラウザ(Cookie)とを紐付けることができます。

 


管理画面での確認

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

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

SATORIで予約されているパラメータについては、項目名が表示され、任意で設定いただいたパラメータにはパラメータ名のみが表示されます。