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

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

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

SATORIのAPIはカスタマー情報の登録・更新・削除が中心で、汎用的な「全件取得」エンドポイントは公開されていません。見込み客リストをまとめて外部へ取り出したい場合は、管理画面のCSV出力か、別料金の「データ提供オプション」を使います。本記事は、外部システムからSATORIへデータを送り込む方向の連携に絞って手順をまとめます。

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

SATORI自身も、このAPIの想定用途を「既存フォームからSATORIへカスタマー情報を登録するため」と明確に限定しています。基幹システムとSATORIの双方でカスタマー情報を管理し続ける必要がある場合や、既存フォームのデザインを変更できない場合が主な利用ケースで、短時間に集中したリクエストや大量データの同期のような使い方は想定されていません。実装前にこの前提を関係者と共有しておくと、後から「なぜバッチ的な使い方ができないのか」という手戻りを避けられます。

APIキーを4種類取得する

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

カンパニーアクセスキーとカンパニーシークレットキーは、管理責任者または管理者権限を持つユーザーしか取得できません。また、キーの取得元ユーザーが「ユーザーロックされていない」「退会処理されていない」「該当APIの操作権限を持つ」の3条件を満たしている必要があります。権限が不足していると、キー自体は取得できてもAPI呼び出し自体が拒否されるため、実装前に取得元ユーザーの権限ルールで該当API操作の実行権限が付与されているかを確認してください。

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

SATORIが公開しているAPIは3種類あります。それぞれ役割が明確に分かれているため、まず自社のユースケースがどれに当たるかを決めてから実装に入るのが効率的です。

APIバージョン4は「新規登録用(registration.json)」「新規登録・更新用(upsert.json)」「削除用(delete.json)」の3エンドポイントに分かれます。upsert.jsonは指定したemail(またはhashcode)が未登録なら新規登録、登録済みなら更新として動きますが、既に値が入っている項目に空欄を送っても上書きされません。この挙動を知らずに実装すると「送ったのに反映されない」という問い合わせにつながりやすい点です。

カスタマーバルクAPIは、CSVファイルを直接POSTする点がAPIバージョン4と異なります。登録・更新のリクエストを送った後、処理が非同期で走るため、status.jsonエンドポイントで処理状況を別途取得する2段構えの設計です。フォーム連携のようにリアルタイム性が必要な場面には向かず、月次の名刺データ一括登録のようなバッチ処理に向いています。カスタマーアクション追加APIは他の2つと違い、カスタマー本体の情報ではなく行動ログを追加する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"

実際のリクエストはapplication/x-www-form-urlencoded形式のPOSTです。curlで最小構成を確認してから、言語・フレームワークに合わせてClaude Codeにポーティングさせる流れが早く安定します。

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

セキュリティ上、SATORIはクライアントサイドのJavaScriptからのAPI呼び出しを認めていません。フォームを受けるサーバーサイド(またはサーバーサイドのスクリプト)からのみリクエストを送る設計にする必要があります。Claude Codeでコードを書かせる際も、フロントエンドのコードにAPIキーが混ざっていないかをレビューさせると事故を防げます。ブラウザの開発者ツールでネットワークタブを開き、APIキーを含むリクエストがサーバー経由になっているかを目視で確認する工程も、実装後の最終チェックとして有効です。

エラーレスポンスとよくあるつまずき

SATORIのAPIはJSON形式でレスポンスを返します。成功時は{"status":200,"message":{"customer[hashcode]":"..."}}のようにハッシュコードが返り、これはメールアドレスとCookieを紐付ける後続処理(計測タグへのパラメータ付与)で使います。

失敗時のステータスコードは次の通りです。

409エラーは、フォーム送信のダブルクリック対策が入っていないケースで特に出やすいエラーです。Claude Codeに実装させる際は、送信ボタンの二重押下防止とリトライ処理をセットで指示すると、実運用でのConflict頻発を減らせます。

もう一つ見落としやすいのが、カスタマーカスタム項目です。フォームの入力項目がSATORI標準のカスタマー項目(氏名・会社・部署など)に無い場合、事前に管理画面でカスタマーカスタム項目を設定し、customer[custom:識別名]という形式でパラメータ名を組み立てる必要があります。この設定を飛ばしてパラメータだけ送っても、値は登録されずに黙って無視されます。

実装後は、本番のフォームに接続する前に必ずテスト用のメールアドレスで一通り動作確認しておくと安心です。新規登録・更新・削除の3パターンをそれぞれ試し、管理画面のカスタマー詳細画面で登録内容が意図通りに反映されているかを目視確認する工程を挟むと、パラメータ名の綴り間違いのような単純なミスをリリース前に潰せます。Claude Codeにテストケースの生成を頼む場合も、正常系だけでなく必須パラメータ欠落やメールアドレス形式エラーのような異常系を含めて書かせると、エラーハンドリングの抜け漏れに気づきやすくなります。

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

SATORIのAPI自体はシンプルなREST APIで、公式が提供する自動生成コードやSDKはありません。その分、フォームの項目定義からリクエスト構築、エラーハンドリング、リトライ設計までを一括りにしてClaude Codeに実装させる余地が大きい領域です。APIキーの管理とクライアントサイドへの露出防止だけは、コードレビューの最終確認として人の目を通す運用にしておくと、キー漏洩の事故を防げます。

取り込んだ見込み客データを分析側で使いたい場合は、APIの守備範囲が登録・更新・削除に寄っている点を前提に設計します。全件取得のエンドポイントが公開されていない以上、分析用のデータは管理画面のCSV出力か「データ提供オプション」から取り出し、APIは書き込み方向に限定する構成が扱いやすくなります。

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

よくある質問

SATORIとClaude Codeを繋ぐ公式MCPサーバーはありますか

SATORIのヘルプセンターを確認するかぎり、2026年8月時点で公式MCPサーバーの提供は確認できていません。連携はAPIキーを使ったREST API呼び出しで実装します。

バルクAPIと通常のAPIバージョン4はどちらを使うべきですか

1件ずつのリアルタイム登録(フォーム送信時など)はAPIバージョン4、まとめて多くのカスタマー情報を登録・更新する場合はカスタマーバルクAPIを使います。バルクAPIはCSVファイルをPOSTする形式で、処理状況はstatus.jsonで別途確認します。

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

管理画面から該当キーを再発行できます。再発行すると旧キーは即座に無効になるため、連携システム側のキーも同時に更新する必要があります。

カスタマーアクション追加APIで登録したスコアはスコア定義に従いますか

従いません。カスタマーアクション追加API経由で登録したスコアは、SATORI管理画面のスコア定義を無視してそのまま書き込まれます。既存のスコアリング設計と競合しないよう、スコア値の設計は事前にすり合わせてください。

独自フォームのデザインを変えたくない場合、APIは必須ですか

必須ではありません。SATORIはフォーム機能自体を持っており、既存フォームのデザインを変更できない場合や、自社の基幹システムでも並行してカスタマー情報を管理し続けたい場合に限り、API連携が候補になります。デザイン変更が可能なら、SATORI標準のフォーム機能を使う方が実装コストは低くなります。