Data connectorsはAPIを使って外部システムと接続し、既存データの取得や更新を行います。そのため、IntercomでData connectorsを設定する際にはいくつかのポイントを押さえることが重要です。
サードパーティAPI（Shopify、WooCommerceなど）の利用
IntercomのData connectorsでサードパーティ（社内開発ではない）APIを利用する場合、その動作やリクエストに対するレスポンスをほとんど制御できないことが多いです。
とはいえ、以下のガイドは有用な指針ですが、一部のセクションはあなたのユースケースに完全には適用できない場合があります。
ファーストパーティAPIの利用
当社のエンジニアは、FinおよびData connectorsと連携するために既存のAPIを設計または修正する際に注意すべきポイントをまとめました。
認証と識別に関する考慮事項
Data connectorsで使用するためのusersおよびユーザー入力のセキュリティ確保方法
重要：あなたやセキュリティチームはリスク評価を実施し、データ漏洩の影響を評価すべきです。
Intercomは、あなたや第三者のAPIの不適切な認証・識別方法によるデータ漏洩について、一切の責任を負いません。
まず、Messenger SecurityをJWTsで有効化することを強く推奨します。Messengerのセキュリティ確保は統合設定で最も重要なセキュリティ対策です。
また、JavaScript APIを通じて複数の属性に署名できるため、REST APIなど別の統合を使わずにMessenger経由でusersに関するデータを安全に送信できます。
安全にデータを送信する利点を活用するために、不安全なMessenger更新から属性を保護し、JWTが安全なソースとみなされるため、送信されたJWTはユーザーのそのフィールドを更新します。これはData connectorsが機密データを扱う場合やデータを操作する場合に重要です。
例えば、Data connectorが“GET /accounts/<account_id>/invoices”というAPIリクエストを行う場合、account_idが保護されていることを確認し、ユーザーが単にaccount_idを列挙してデータを収集できないようにします。しかし、Data connectorが"GET /pizza-order-status/<order_id>"の場合は、"order_id"の信頼性を気にせず、その情報が正しい人に表示されるかどうかを気にしないかもしれません。
さらに、Data connectorがusersを一意に識別するために使用する属性（例えばemail）が信頼できることを確認すべきです。つまり、Data connectorの識別属性のソースを信頼している必要があります。例えば、Data connectorがuser_idでユーザーを識別する場合はuser_id属性に署名し、emailや他の属性で識別する場合はその属性が保護され、エンドユーザーからの検証なしに収集されないことを意味します。
これにより、悪意のある者が他人のemailアドレスを提供して「Get bank statements by email」などのData connectorにアクセスし、機密の金融データを露出させることを防ぎます。
可能であれば、usersのデータ取得の主な識別子としてemailを使用しないことをお勧めします。代わりに、推測不可能な一意のuser IDなど、よりランダムなものを使うべきです。
leadsの本人確認を行うために、当社チームは現在、サポートに連絡するleadsの本人確認を支援するワンタイムパスワード（OTP）機能を開発中です。この機能に興味がある場合は、Messenger経由でサポートチームにお問い合わせください。導入をお手伝いします。
また、ユーザーが権限のないData connectorsを実行できないようにする必要があります。例えば、注文IDを知って他人の注文をキャンセルすることなどです。このロジックはIntercom内で処理されないため、あなたやセキュリティチームがリスク評価を行い、認証と認可を適切に処理する方法を考案すべきです。
Data connectorのAPI呼び出しを安全に設定する方法
Intercomは現在、静的トークン、HTTPトークン、およびOAuth（クローズドベータ、詳細はMessenger経由でお問い合わせください）をサポートしています。どのトークンを使うにせよ、漏洩した場合は速やかに更新し秘密を保持する責任があります。ベストプラクティスとして、可能な限りOAuthトークンの使用を推奨します。
データに関する考慮事項
理想的には、APIはWorkflowに必要なデータのみを返すべきです。しかし現実的には、Data connectorが使われるWorkflowを実行するのに不要なデータも多く返すことがあります。
Data connectorsおよびFin Workflows専用にAPIを一から構築する場合、以下のいずれかの方法が考えられます。
Workflowのビジネスロジックを1つのData connectorで処理できるようAPIを構築する方法 - これによりAPIコール数が削減され、ロジックが一箇所にまとめられます。
注文検索、注文詳細取得、注文の返金など個別のエンドポイントを構築する方法 - これはRESTful APIのベストプラクティスに沿っていますが、1つのWorkflow（例：注文返金）を完了するのに複数のAPIコールが必要です。
APIが返すデータの内容や量を決める際に考慮すべき点には以下があります。
Fin/WorkflowがWorkflowのステップを完了するために本当に必要なデータは何か？例えば、注文返金のWorkflowでは注文の詳細だけが必要で、特定のusersアカウントに関する追加データは不要かもしれません。
Data connectorsのタイムアウトは15秒です。APIの応答が遅い場合は、処理内容や返すデータ量を減らすことを検討すると良いでしょう。
完了に時間がかかるData connectorsには“Wait for webhook”機能の利用を推奨します。Data connectorsは1〜2階層のネストされた属性や配列には簡単にアクセスできますが、深くネストされた複雑なオブジェクトはFin Proceduresで処理する方が適しています。これらのタイプのレスポンスオブジェクトをData connectorで使おうとすると困難が生じる場合がありますが、Fin Tasksはより扱いやすいです。
注意：Fin Proceduresを使用する場合、Data connectorsのタイムアウトは（特定の対象ワークスペースで）30秒となり、デフォルトの15秒より長くなります。これは長時間実行されるAPIコールを含むWorkflow設計時に重要な違いです。
さらに、usersが不正なデータを提供したり、単に入力したりすることを常に防ぐべきです。
例えば、ユーザーにアカウントIDを入力させるのではなく、既知の安全な識別子に基づくアカウントIDを提示し、ドロップダウンリストから選択させるべきです。ユーザーからのデータ収集方法の詳細はこちらをご覧ください。
その他の考慮事項
APIは、1日あたりの返金上限など、アプリケーション固有の制限を強制すべきです。
Finは同じ返金リクエストを複数回送信する可能性があるため、APIは冪等性を確保してください。
Data connectorで指定された形式にすべての入力が準拠していることを確認するため、サーバー側でのバリデーションを実装してください。
AI生成フィールドに幻覚や悪意のある内容が含まれる可能性があることを認識し、受信データの入力サニタイズを適用してください。
Finが適切に応答できるよう、標準的なHTTPエラーコードを使用してください。例えば、HTTP 429や500エラーは再試行が必要ですが、HTTP 410はこれ以上の試行を行わないことを示します。
Live Fin Data connectorsのバージョン間のシームレスな移行を可能にするため、APIのバージョン管理を行ってください（例：/v1/ordersから/v2/orders）。
まとめ
JWTsでMessengerを保護し、usersのデータと属性を守る。
信頼できる識別子を使用（例：署名済みuser IDs、emailではない）してデータを取得。
ユーザーの操作を制限し、許可された範囲内のみにする。
自由入力を避ける — 既知で安全なソースからのドロップダウンを使用。
安全なAPIトークンを選択、理想的にはOAuth（クローズドベータ）。
必要なデータのみ返すことで遅延やデータ漏洩を防ぐ。
明確なAPI構造を使用 — シンプルなレスポンス、適切なバージョニング、標準的なエラーコード。
すべての入力を検証し、ユーザーやAI生成のものはサニタイズする。