Sansan Open API認証フローと連携ガイド

認証フローの選定と実装

Sansan Open APIを利用する際、API KeyとOAuthの2つの認証方法が利用可能です。どちらを選ぶかはシステムの信頼性やセキュリティ要件によって異なります。本セクションでは両者の特徴を比較し、実務での選定ポイントを解説します。

API KeyとOAuthの比較

API Key方式は単純な文字列の認証で、外部システムとの連携が比較的容易です。一方、OAuthはユーザーごとに認証トークンを発行するため、セキュリティ性に優れています。

注意: API Keyは秘密管理が重要です。漏洩時はすぐに無効化し、代替の認証手段に切り替える必要があります。

セキュリティベストプラクティス

Sansan公式ドキュメントでは、OAuthを推奨しており、特に外部システムとの連携時には必ずOAuth方式を採用することを強くお勧めします。また、API Keyを使用する場合でも、環境変数による管理や定期的なローテーションが不可欠です。

名刺データ同期の標準フォーマット

Sansan APIでは、JSONとXMLの2つの形式で名刺データを取得・送信できます。外部システムとの整合性を保つためには、フィールドマッピングの精度に注意が必要です。

JSONとXMLの構造例

以下は、JSON形式での名刺データのサンプルです。主な項目（氏名・所属・連絡先）が含まれています。

XML形式の場合、同じデータは以下のように表現されます。

フィールドマッピングの注意点

外部システム（例: Salesforce）との連携では、Sansanのフィールド名と対応する項目を明確に定義することが重要です。特に以下の点に気を配りましょう。

• データ型の一致: メールアドレスは必ずstringで、電話番号はtextまたはphone形式にする
• 必須項目の確認: Salesforceの「Account Name」や「Lead Source」などの必須フィールドがある場合、連携設計時に事前に確認する
• デフォルト値の設定: データが空欄の場合にどう処理するかを明文化

注意: JSON/XML例におけるフィールド名とSansan API仕様との整合性確認が必要です。公式ドキュメントで再確認してください。

Data Hub APIによる顧客データ統合手順

Data Hub APIは、Sansanと外部システム（CRM・SFA）の間でデータを統合する際の中心的な役割を果たします。ここでは連携フローの設計例と、処理方法の選定基準を解説します。

連携フローの設計例

1. SansanからData Hubにデータ送信
2. 名刺情報をAPI経由でData Hubに登録
3. Data Hubによるデータ統合処理
4. データベース内での重複チェックやフォーマット変換を行う
5. 外部システム（例: Salesforce）への同期
6. Change Feed APIを介してリアルタイムでデータを反映

注意: Data Hubの利用には、通常のSansan契約に加えて、Data Hubサービスの別途契約が必要です。公式サイトからご確認ください。

バッチ処理とリアルタイム処理の選定基準

主な外部システムとの連携例

SansanはSalesforce、Dynamics 365など多くのクラウドシステムと連携可能です。以下では実際の導入事例をもとにした手順を紹介します。

Salesforce連携の具体的手順

1. Sansan側でのAPI設定
2. Salesforceに接続するためのOAuthクライアントIDとシークレットを取得
3. Salesforce側のAPI設定
4. Sansanから送信されるデータ項目がSalesforceのフィールドにマッチするように設計
5. Data Hub APIとの連携
6. 名刺データをData Hub経由でSalesforceに同期

参考: SalesforceとSansanをAPI連携する際は、公式ドキュメントの「Salesforce連携ガイド」を必ず参照してください。

Dynamics 365統合のケーススタディ

Dynamics 365との連携では、REST APIとWebhookの組み合わせが有効です。以下がポイントです：

• データ同期: 名刺情報を定期的にDynamics 365に送信
• 変更検出: Change Feed APIでSansan側の更新をリアルタイムで感知
• エラーハンドリング: エラー発生時に再試行ロジックを組み込む

変更フィードAPIの活用方法

Change Feed APIは、Sansan内のデータ変更（新規登録・更新）をリアルタイムで検出する機能です。業務システムとの連携においては、このAPIを活用することでデータの即時同期が可能になります。

イベントタイプの分類

Change Feed APIでは以下のようなイベントタイプがあります：

• CREATED: 新規登録された名刺
• UPDATED: 編集された情報（氏名・所属など）
• DELETED: 削除されたデータ

注意: イベントタイプごとに処理ロジックを分けることで、システムの信頼性が向上します。

リアルタイム処理の実装パターン

以下のように設計することで、リアルタイムなデータ同期が可能になります：

1. Change Feed APIをポーリング: 指定間隔で変更イベントを取得
2. Webhookによる通知: 変更発生時に自動的に外部システムへ通知
3. データの適用: 取得したイベント情報を、業務システムに反映

実装にあたっての準備と連携体制

Sansan API導入には事前準備が不可欠です。以下は、導入前のチェック項目と、クロスファンクショナルチームの役割分担を解説します。

事前調査すべきドキュメント一覧

• Sansan公式ドキュメント「API連携について」
• Data Hub API仕様書（変更フィードやデータ同期の詳細）
• 外部システム（Salesforceなど）のAPI仕様書

クロスファンクショナルチームの役割分担

CTA: Sansan公式ドキュメントを参照しつつ、システム担当者と連携してAPI設定に取り組んでください。