APIバージョン4の利用方法（カスタマー新規登録・更新・削除）

最終更新日：

2021/11/11のUI刷新 第一弾リリースにてカラースキーム(配色設計)とタイポグラフィ(文字の書体、大きさ、配列のしかたなど)を変更しております。オンラインマニュアルに掲載している画面キャプチャと実際の管理画面の配色や文字の状態が異なる場合がございますがご了承いただけますと幸いでございます。

attention.png API連携はサーバーサイドスクリプトのプログラム開発が必要になるため、一定のWeb技術の知識が必要となります。
SATORI APIを利用した貴社システム側との連携方法や実装支援などはサポート範囲外とさせていただいており、
API連携に関してお伝えできる情報としましては、以下マニュアルに掲載されている情報のみとなります。
また、運用開始後にうまく連携されない場合のエラー解析やデバッグ対応についてもサポート範囲外となります。
技術的な知識を有している担当者様、もしくは連携先APIの仕様を理解されている担当者様に相談のうえ実装をご検討ください。

APIバージョン4について

APIバージョン4を利用すると、SATORIのフォーム機能で作成したものではない貴社の既存フォームからカスタマー情報が新規登録・更新された際に、SATORI全体で共通で用意されているカスタマー属性項目だけでなく、独自に設定したカスタマーの属性項目であるカスタマーカスタム項目へも、情報の反映が可能となります。

APIバージョン4を利用してカスタマーカスタム項目へも情報反映を希望される場合、まずはカスタマーカスタム項目の設定が必要となります。

カスタマーカスタム項目の設定については以下から詳細をご確認ください。

「カスタマーカスタム項目について」

「カスタマーカスタム項目FAQ」

 

注意・確認事項

■貴社の既存フォームからSATORIへカスタマー登録をするための目的で公開しているAPIです。
短時間に集中したリクエスト、または一度に大量なリクエストを必要とするようなカスタマー情報の同期など、意図しない目的でのご利用はご遠慮ください。

■カレント以外のバージョンは非推奨となっており、本マニュアルに記載のないコードの提供は行っておりません。
ご了承いただけますようお願いいたします。

■API をJavaScript で呼び出しすることはセキュリティの観点からご遠慮いただいております。サーバーサイドスクリプトにてご用意いただけますようお願いいたします。（サーバーサイドのJavaScript であれば可）

■APIの利用が必要になるケースとして下記が挙げられます。APIのご利用の前にご確認ください。
・貴社の基幹システム等でカスタマー情報を保有（既存フォームから基幹システムへカスタマー情報を登録）しており、引き続きその基幹システム／SATORIの双方でカスタマー管理を行う必要がある場合。
・貴社のCIが厳しく、既存フォームのデザインを変更することが一切不可能な場合。
※上記のケースに該当しない場合は、SATORIのフォーム機能のご利用をおすすめしております。

 

API利用の流れ（概要）

① 貴社の既存フォームからカスタマーが項目を入力してデータ登録（入力内容をWebサーバーへPOST）
② 1のフォームを構築しているアプリケーションからSATORI API（URL）をリクエスト
③ 2のリクエスト内容が正しければSATORIのカスタマー管理へカスタマー情報登録の処理を行う
④ 3の登録処理結果がSATORI APIに返却される
⑤ SATORI APIから1のフォームを構築しているアプリケーションにレスポンスが返却される
⑥ レスポンス処理を行う
※レスポンス処理については、このページ下部の「レスポンスの処理」項目をご確認ください。

 

flow.png

 

前提事項

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

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

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

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

 

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

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

  • 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/v4/public/customer/registration.json
  • 送信するパラメータリスト

※貴社の既存フォームに対応するパラメータを以下の表よりご選択ください。
既存フォームに存在して以下の表に無いものは、「カスタマーカスタム項目」を追加設定することで対応させることが可能です。
※カスタマーカスタム項目へ連携する場合は、このページ下部の「カスタマーカスタム項目のパラメータ名とデータについて」項目をご確認ください。

パラメータ名 日本語名 必須 備考
user_key ユーザー
アクセスキー		 ◯ 管理画面より取得
user_secret ユーザー
シークレットキー		 ◯ 管理画面より取得
company_key カンパニー
アクセスキー		 ◯ 管理画面より取得
company_secret カンパニー
シークレットキー		 ◯ 管理画面より取得
customer[identity_type] 識別タイプ ◯ 新規登録用は「email」のみ指定可
customer[email] メールアドレス ◯

メールアドレスに使用できる文字やルール
・メールアドレスとして適切な文字列で半角のみ
・最大255文字
・@の左側に使用できる記号は「-(ハイフン)」「_(アンダースコア)」「.(ドット)」「+(プラス)」
・@の右側（ドメイン）に使用できる記号は「-(ハイフン)」「.(ドット)」

メールアドレスに使用できない文字やルール
・先頭文字に「-(ハイフン)」「.(ドット)」「_(アンダースコア)」は使用できません
NG例：-sample@example.com
          .sample@example.com
          _sample@example.com
・@の直前に「.(ドット)」は使用できません
NG例：sample.@example.com
・@の直後に「.(ドット)」は使用できません
NG例：sample@.example.com
・「.(ドット)」を連続使用はできません
NG例：sample..a@example.com
・日本語は使用できません
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
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[delete_tags] タグ - 最大255文字
カンマ区切りタグを複数指定可能
"(" ")" "AND" "NOT" "OR" を含まない文字列
(例: メルマガ登録, サイト訪問者)
customer[memo] メモ - 最大500文字
customer[custom:識別名] カスタマーカスタム項目 - データは、カスタマーカスタム項目で設定したデータ・タイプ、バリデーションタイプに準ずる

 

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/v4/public/customer/registration.json

 

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

upsert.json の動作

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

リクエストについて

  • Content-Type： application/x-www-form-urlencoded
  • 文字コード： UTF-8
  • APIのURL： https://api.satr.jp/api/v4/public/customer/upsert.json
  • 送信するパラメータリスト

※貴社の既存フォームに対応するパラメータを以下の表よりご選択ください。
既存フォームに存在して以下の表に無いものは、「カスタマーカスタム項目」を追加設定することで対応させることが可能です。
※カスタマーカスタム項目へ連携する場合は、このページ下部の「カスタマーカスタム項目のパラメータ名とデータについて」項目をご確認ください。

パラメータ名 日本語名 必須 備考
user_key ユーザー
アクセスキー		 ◯ 管理画面より取得
user_secret ユーザー
シークレットキー		 ◯ 管理画面より取得
company_key カンパニー
アクセスキー		 ◯ 管理画面より取得
company_secret カンパニー
シークレットキー		 ◯ 管理画面より取得
customer[identity_type] 識別タイプ ◯ 更新用は「email」または「hashcode」を指定可
レスポンスで取得できるcustomer[hashcode]で更新を行いたい場合は「hashcode」を指定
customer[email] メールアドレス ◯

メールアドレスに使用できる文字やルール
・メールアドレスとして適切な文字列で半角のみ
・最大255文字
・@の左側に使用できる記号は「-(ハイフン)」「_(アンダースコア)」「.(ドット)」「+(プラス)」
・@の右側（ドメイン）に使用できる記号は「-(ハイフン)」「.(ドット)」

メールアドレスに使用できない文字やルール
・先頭文字に「-(ハイフン)」「.(ドット)」は使用できません
NG例：-sample@example.com、.sample@example.com
・@の直前に「.(ドット)」は使用できません
NG例：sample.@example.com
・@の直後に記号は使用できません
NG例：sample@.example.com
・「.(ドット)」を連続使用はできません
NG例：sample..a@example.com
・日本語は使用できません

* APIリクエスト時のパラメータ identity_type に email を指定した場合は必須
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
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[delete_tags] タグ - 最大255文字
カンマ区切りタグを複数指定可能
"(" ")" "AND" "NOT" "OR" を含まない文字列
(例: メルマガ登録, サイト訪問者)
customer[memo] メモ - 最大500文字
customer[custom:識別名] カスタマーカスタム項目 - データは、カスタマーカスタム項目で設定したデータ・タイプ、バリデーションタイプに準ずる

 

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/v4/public/customer/upsert.json

 

削除用： delete.json

delete.json の動作

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

リクエストについて

  • Content-Type： application/x-www-form-urlencoded
  • 文字コード： UTF-8
  • APIのURL： https://api.satr.jp/api/v4/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/v4/public/customer/delete.json

 

 

レスポンスについて

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

成功時のレスポンスメッセージ

  • 新規登録用： registration.json、新規登録および更新用： upsert.json
{"status":200, "message": {"customer[hashcode]": "8eced811cdb57f56"}}
※メールアドレスに対応したハッシュコードが返却されます。
  • 削除用： delete.json
{"status":200,"message":"OK."}

失敗時のレスポンスメッセージ

  • APIキー不正の場合
{"status":401,"message":"Unauthorized"}
  • 識別タイプの指定がない場合
{"status":400,"message":"validation error: customer[identity_type] required."}
  • 指定したカスタマーが存在しない場合
{"status":404,"message":"Not Found."}
  • メールアドレスがない場合
{"status": 400, "message": "validation error: customer[email] required."}
  • ハッシュコードがない場合
{"status":400,"message":"validation error: customer[hashcode] required."}
  • バリデーションに失敗した場合
{"status":400, "message": "バリデーションに失敗しました。 メールアドレスは不正な値です。"}
  • その他
{"status": 409, "message": "Conflict"}

 

 

レスポンスの処理

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

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


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


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


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

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

 

カスタマーカスタム項目のパラメータ名とデータについて

カスタマーカスタム項目へ連携する場合は、それぞれのカスタマーカスタム項目で設定された識別名がパラメータに必要となります。customer[custom:識別名]となります。

また、カスタマーカスタム項目で設定された「データ・タイプ」と「バリデーションタイプ」に合致していないデータであった場合、レスポンスはエラーとなります。

 

例）カスタマーカスタム項目として「予約日」を識別名「reservation_date」、データ・タイプ「日付」、バリデーションタイプ「なし」で作成した場合

__v4_.png

  • カスタマーカスタム項目「予約日」に対してデータをAPIで連携する際のパラメータ名はcustomer[custom:reservation_date]となります。
  • データ・タイプで選択された「日付」に合致しないデータの場合はエラーとなります。

 

管理画面での確認

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

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

 

apiregis.png 

API通信時のセキュリティについて

 API実行時には下記に対してwebアクセスしております。
https://api.satr.jp

この時、httpsを指定してセキュリティーが保護された環境でapi.satr.jpへ暗号化通信を行う設定となっております。その後は内部ネットワークによる通信を行っているため、外部へ情報が漏洩する可能性はありませんのでご安心くださいませ。

この記事は役に立ちましたか？

4人中2人がこの記事が役に立ったと言っています

SATORIサポートセンターへ問い合わせる 同じカテゴリーの記事一覧に戻る

関連記事

関連記事