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

最終更新日：

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

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

目次

 

APIバージョン4について

APIバージョン4を利用すると、SATORI以外の既存フォームから送信された任意のパラメータを使用して、カスタマー情報を新規登録または更新できます。
外部フォームからAPIを通じて送信されたパラメータは、「カスタマー詳細」に含まれる以下の項目に登録または更新されます。

  • カスタマー項目
  • カスタマーカスタム項目

カスタマーカスタム項目を利用する場合は、事前に設定が必要です。詳細については以下のマニュアルをご参照ください。

API利用の流れ（概要）

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

 

flow.png

前提事項

APIバージョン4では以下3種類のAPIを提供しています。

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

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

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

APIを利用するには以下のAPIキーが必要になります。APIキーはSATORI管理画面より取得できます。

  • user_key : 'ユーザーアクセスキー
  • user_secret : 'ユーザーシークレットキー
  • company_key : 'カンパニーアクセスキー
  • company_secret : 'カンパニーシークレットキー

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

注意・確認事項

  • 貴社の既存フォームからSATORIへカスタマー登録をするための目的で公開しているAPIです。
  • 短時間に集中したリクエスト、または一度に大量なリクエストを必要とするようなカスタマー情報の同期など、意図しない目的でのご利用はご遠慮ください。
  • バージョン4以外のご利用は非推奨となります。
  • 本マニュアルに記載されていないコードの提供は行っておりません。
  • セキュリティ上の理由により、クライアントサイドのJavaScriptを使用してAPI接続を行わないでください。
    API接続は、サーバーサイドスクリプトまたはサーバーサイドのJavaScriptをご利用ください。
  • APIの利用が必要になるケースとして下記が挙げられます。APIのご利用の前にご確認ください。
    ・ 貴社の基幹システム等でカスタマー情報を保有（既存フォームから基幹システムへカスタマー情報を登録）しており、
    　引き続きその基幹システム / SATORIの双方でカスタマー管理を行う必要がある場合。
    ・ 貴社のCIが厳しく、既存フォームのデザインを変更することが一切不可能な場合。
    　※上記のケースに該当しない場合は、SATORIのフォーム機能のご利用をおすすめしております。

新規登録用API (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

 

新規登録および更新用API (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

 

削除用API (delete.json)

delete.json の動作

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

リクエストについて

  • Content-Type : application/x-www-form-urlencoded
  • 文字コード : UTF-8
  • APIのUR : 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フォーマットでレスポンスが返されます。
レスポンスは以下の種類があります。

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

  • 新規登録用API （registration.json） ・ 新規登録および更新用API （upsert.json）
{"status":200, "message": {"customer[hashcode]": "XXXXXXXXXXXXXXXX"}}
※メールアドレスに対応したハッシュコードが返却されます。
  • 削除用API （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"}

※Conflict エラーは、主に以下の状況で発生します。

　・ 短時間に同一リクエストを繰り返し送信した場合
　・ APIサーバー側で予期しないエラーが発生した場合　など

　上記エラーが発生した場合、リクエストやデータが重複していないことを確認し、再度登録処理を実行してください。

 

レスポンスの処理

成功時に返却されるレスポンスを適切に処理することで、メールアドレスとブラウザ (Cookie) を紐付けできます。

  • レスポンス例
 {"status": 200, "message": {"customer[hashcode]": "XXXXXXXXXXXXXXXX"}}
※"XXXXXXXXXXXXXXXX"は、メールアドレスに対応したハッシュコードです

返却されたハッシュコードを使用し、以下のいずれかの方法で紐付けを行ってください。

紐付け方法1

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

例：会員登録完了のサンクスページの場合

https://sample.com/thank_you?c=XXXXXXXXXXXXXXXX-00

紐付け方法2

返却されたhashcodeに-00を追加した値を使用して、以下のJavaScriptを遷移先ページに追加してください。
※scriptタグはSATORI計測タグより上に記述してください。

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

 

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

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

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

 

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

__v4_.png

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

 

管理画面での確認

APIバージョン4でカスタマー情報を登録・更新すると、対象のカスタマーの最新アクション一覧にアクション履歴が追加されます。

アクションタイプは、利用するAPIに応じて次のように表示されます。

  • 新規登録用API （registration.json） : 「API 登録」
  • 新規登録および更新用API （upsert.json） : 「API登録更新」

APIバージョン4の利用方法_20241126_01.png

「API登録」または「API登録更新」の「内容」をクリックすると、以下のように送信内容を確認できます。

apiregis.png 

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

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

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

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

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

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

関連記事

関連記事