Claude SATORI連携ガイド — APIキー取得から実装まで

SATORIとClaudeを連携する前に確認すること

SATORIはマーケティングオートメーション(MA)ツールで、見込み客(カスタマー)情報の登録・更新やアクション履歴の追加をWeb APIで公開しています。ただしSlackやNotionのような公式MCPサーバーは、SATORIのヘルプセンターを確認するかぎり提供されていません。連携はREST形式のAPIをサーバーサイドのプログラムから呼び出す形になり、Claude Codeが得意とするのはこの実装作業そのものです。

API連携はサーバーサイドの開発が前提です。SATORIのサポート窓口は連携先システムの実装支援や、運用開始後のエラー解析・デバッグ対応を範囲外としています。実装自体をClaude Codeに任せる価値が大きい領域です。

そもそもAPIが必要な状況か

ヘルプセンターの「外部サービスとの連携について」には、SATORIと外部をつなぐ方法が9通り挙がっています。APIはそのうちの3つにすぎません。データの流れる向きで分けると、自分の状況に合う手段が見えます。

APIの想定用途は、既存フォームからSATORIへカスタマー情報を登録することです。短時間に集中したリクエストや、大量データの同期のような使い方は「意図しない目的」として控えるよう求められています。APIが候補になる場面として挙がっているのは、次の2つです。

• 基幹システムとSATORIの双方でカスタマー情報を管理し続ける必要がある
• 既存フォームのデザインを一切変更できない

どちらにも当てはまらない場合、SATORIはフォーム機能の利用を勧めています。実装前にこの前提を関係者と共有しておくと、後から「なぜバッチ的な使い方ができないのか」という手戻りを避けられます。

本記事は、外部システムからSATORIへデータを送り込む方向の連携を扱います。見込み客リストをまとめて外部へ取り出したい場合は、上の「SATORIから外部へ出す」側の手段が候補です。

APIキーを4種類取得する

SATORIのAPIを呼び出すには、管理画面から取得する4種類のキーが必須です。

カンパニーアクセスキーとカンパニーシークレットキーは、管理責任者または管理者権限を持つユーザーしか取得できません。キーの取得元ユーザーには、さらに3つの条件があります。

• ユーザーロックされていない
• 退会処理されていない
• 各APIの操作に必要な権限が付与されている

見落としやすいのが最後の条件です。管理画面で設定した権限ルールは、API経由の操作にも適用されます。必要な権限ルールの項目はAPIごとに違います。

カスタマー情報の編集とカスタマーの削除が「自分のみ」になっているユーザーのキーでは、自分のAPIキーで登録したカスタマーか、自分が管理画面から登録したカスタマーにしか操作が通りません。他のユーザーや他のAPIキーで登録されたカスタマーは対象外です。upsert.jsonが通る相手と通らない相手が混在して見えるときは、キーの発行元ユーザーの権限ルールを疑う価値があります。

キーを再発行すると、現在のアクセスキーとシークレットキーは無効になります。連携システム側のキーを差し替えるまで、呼び出しは認証エラーになります。

3種類のAPIから用途に合ったものを選ぶ

SATORIが公開しているAPIは3種類あります。

バージョン4以外の利用は非推奨とされています。既存の連携コードを引き継ぐ場合は、どのバージョンを呼んでいるかを最初に確認してください。

registration.jsonとupsert.jsonは「既存の値の扱い」が違う

APIバージョン4で迷いやすいのが、新規登録用と新規登録・更新用の使い分けです。名前から「どちらも登録できる」と受け取りがちですが、既に登録済みのカスタマーに対する挙動が異なります。

どちらも「空欄で消す」ことはできないため、フォーム側で項目を空にして再送信しても、SATORI側の値は残ります。値を消したい場合は、管理画面で操作する前提で設計します。

カスタマーバルクAPIは、CSVファイルを直接POSTする点がAPIバージョン4と異なります。リクエスト後の処理は非同期で、status.jsonで処理状況を別途取得する2段構えです。フォーム連携のようなリアルタイム性が必要な場面には向かず、月次の名刺データ一括登録のようなバッチ処理に向いています。

1回のPOSTに含めるカスタマーデータは10,000件以下、ファイルサイズは10MB程度までです。超える場合は1万件以下に分けて直列に送り、status.jsonで完了を確認してから次をPOSTします。process_codeは発行から72時間後に無効になります。

カスタマーアクション追加APIは、カスタマー本体の情報ではなく行動ログを追加するAPIです。登録したスコアはスコア定義を無視して、指定した値がそのまま書き込まれます。

Claude Codeで連携スクリプトを実装する

自社フォームの入力項目とSATORIのパラメータ名を対応させる作業は、項目数が増えるほど時間を取られます。Claude Codeにフォームのフィールド定義とSATORIのパラメータ表を渡すと、マッピングコードと送信スクリプトを一度に書かせられます。

claude -p "自社フォームのフィールド定義(form-schema.json)を読み、
SATORI upsert.json 用のリクエストボディを組み立てるNode.jsスクリプトを書いて。
customer[email] は必須、customer[collection_route] は固定値『問合せフォーム』にする" \
  --allowedTools "Read,Write"

-p(--print)は応答を出力して終了する非対話モードで、--allowedToolsは許可するツールを指定するフラグです。v2.1.287のclaude --helpで、どちらも存在することを確認しました。ここでは読み取りと書き込みだけを許可し、Bashは許可していません。生成されたスクリプトは人が読んでから実行する運用になります。

プロンプトにcustomer[collection_route]を明記しているのは、情報獲得経路が必須項目だからです。registration.jsonとupsert.jsonのどちらでも、メールアドレスと並んで必須になっています。必須項目の抜けは400エラーの原因になるため、プロンプトに書いておく価値があります。

実装の進め方

実際のリクエストはapplication/x-www-form-urlencoded形式(文字コードはUTF-8)のPOSTです。最小構成は次のとおりです。

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

メールアドレスの「+」はエンコードが必要

公式のメールアドレスの規則では、@の左側に+を使えます。ところがフォーム形式のボディでは、+はスペースとして解釈されるのが通常の扱いです。curl -dは値をエンコードしないため、test+a@example.comをそのまま渡すと意図しない値になるおそれがあります。--data-urlencodeなら、curlが値をエンコードします。

JavaScriptで組み立てる場合はURLSearchParamsが使えます。Node.js 20.18.0で、APIを呼ばずにボディの文字列だけを出力して確かめました(キーはダミー、通信はしていません)。

const body = new URLSearchParams({
  "customer[identity_type]": "email",
  "customer[email]": "test+a@example.com",
  "customer[custom:reservation_date]": "2026-10-02",
});
console.log(body.toString());

出力は次のとおりです(一部を省略)。

customer%5Bidentity_type%5D=email&customer%5Bemail%5D=test%2Ba%40example.com&customer%5Bcustom%3Areservation_date%5D=2026-10-02

[と]は%5Bと%5Dに、+は%2Bに、コロンは%3Aに変換されます。Claude Codeにスクリプトを書かせるときは、手書きの文字列連結ではなく、エンコード済みのボディを組み立てる標準の仕組みを使うよう指示すると、この種の事故を避けられます。

クライアントサイドから呼ばない

SATORIはセキュリティ上の理由で、クライアントサイドのJavaScriptからのAPI接続を認めていません。フォームを受けるサーバーサイド、またはサーバーサイドのJavaScriptからだけリクエストを送る設計にします。Claude Codeでコードを書かせる際は、フロントエンドのコードにAPIキーが混ざっていないかをレビューさせると事故を防げます。ブラウザの開発者ツールのネットワークタブで、APIキーを含むリクエストがサーバー経由になっているかを目視する工程も、最終チェックとして使えます。

レスポンスの読み方と、ブラウザとの紐付け

SATORIのAPIはJSON形式でレスポンスを返します。成功時の形は、APIによって違います。

返ってくるhashcodeは、メールアドレスに対応した値です。サンクスページなどの遷移先で、メールアドレスとブラウザ(Cookie)を紐付けるのに使えます。方法は2つあり、どちらも遷移先ページにSATORI計測タグが設置されていることが前提です。

• hashcodeに-00を付けた値を、遷移先URLのcパラメータに足す(例: https://sample.com/thank_you?c=XXXXXXXXXXXXXXXX-00)
• 同じ値をスクリプトで渡す。var StDmp = {}; StDmp.additionalParams = { c: "XXXXXXXXXXXXXXXX-00" };のように、先にStDmpを宣言します。このscriptタグは計測タグより上に書く

失敗時のステータスと対処

失敗時のレスポンスは、原因ごとにメッセージが決まっています。

409の公式の対処は「リクエストやデータが重複していないことを確認し、再度登録処理を実行してください」です。フォームの二重押下防止と、重複していないことを確かめたうえでの再試行は、Claude Codeへの実装指示に含められます。再試行を無条件にループさせると、同一リクエストの繰り返しという409の原因をなぞることになるため、間隔と回数の上限を決めて書かせます。

カスタマーカスタム項目のつまずき

フォームの入力項目がSATORI標準のカスタマー項目(氏名・会社・部署など)に無い場合は、事前に管理画面でカスタマーカスタム項目を設定します。パラメータ名はcustomer[custom:識別名]の形で組み立てます。

識別名は、管理画面でカスタマーカスタム項目に付けた名前です。たとえば識別名reservation_date、データ・タイプ「日付」で作った「予約日」なら、パラメータ名はcustomer[custom:reservation_date]になります。設定したデータ・タイプやバリデーションタイプに合わない値を送ると、レスポンスはエラーになります。

公式のAPIバージョン4の説明が述べているのは、標準項目に無い入力項目はカスタマーカスタム項目を追加設定して対応させること、型が合わなければエラーになることまでです。未設定の識別名を送ったときの挙動は書かれていません。テスト用アドレスで実際に送って確かめるのが確実です。

送ったデータを管理画面で確かめる

APIバージョン4でカスタマー情報を登録・更新すると、対象カスタマーの最新アクション一覧にアクション履歴が追加されます。アクションタイプはregistration.jsonが「API登録」、upsert.jsonが「API登録更新」です。「内容」をクリックすると、送信内容を確認できます。

パラメータ名の綴り間違いのような単純なミスは、この履歴で本番前に見つかります。Claude Codeにテストケースの生成を頼む場合は、正常系だけでなく異常系も書かせます。必須パラメータの欠落やメールアドレスの形式エラーを含めておくと、エラーハンドリングの抜け漏れに気づきやすくなります。

まとめ — SATORI API連携はどこまでをClaude Codeに任せられるか

APIの仕様がシンプルで、公式のマニュアルにパラメータ表とcurlの例がそろっているため、リクエストの構築・エラー処理・リトライの設計はClaude Codeに任せやすい領域です。人の目を残すのは、キーの管理とクライアントへの露出防止、そして「そもそもAPIを使う状況か」の判断になります。

SATORI以外のMCP対応サービスとの連携パターンは、Claude Code MCP設定ガイドやおすすめMCPサーバー10選が参考になります。マーケティング業務全般でのClaude活用はClaudeマーケティング活用にあります。

よくある質問

APIキーが漏洩した場合はどうすればよいですか

管理画面の「アクセスキーを発行しなおす」から再発行できます。再発行すると現在のアクセスキーとシークレットキーは無効になるため、連携システム側のキーも差し替えます。

バルクAPIを使えば、フォームからの登録を大量にさばけますか

フォームからの登録には向きません。大量データの同期は、APIバージョン4の想定用途の外とされています。まとめて登録する用途がバルクAPIの役割で、CSVをPOSTしてstatus.jsonで処理状況を確認します。