Data connectorsはAPIを使って外部システムと接続し、既存データの取得や更新を行います。そのため、IntercomでData connectorsを設定する際にはいくつかのポイントを押さえることが重要です。

サードパーティAPI（Shopify、WooCommerceなど）の利用

IntercomのData connectorsでサードパーティ（社内開発ではない）APIを利用する場合、その動作やリクエストに対するレスポンスをほとんど制御できないことが多いです。

とはいえ、以下のガイドは有用な指針ですが、一部のセクションはあなたのユースケースに完全には適用されないかもしれません。

ファーストパーティAPIの利用

当社のエンジニアが、FinおよびData connectorsと連携するために既存のAPIを設計または修正する際に注意すべきポイントをまとめました。

認証と識別に関する考慮事項

Data connectorsで使用するユーザーとユーザー入力のセキュリティ確保方法

重要：あなたやセキュリティチームはリスク評価を実施し、データ漏洩の影響を評価すべきです。

Intercomは、あなたや第三者のAPIの不適切な認証・識別の実践によるデータ漏洩について、一切の責任を負いません。

まず、Messenger Security with JWTsの有効化を強く推奨します。Messengerのセキュリティ確保は統合設定で最も重要なセキュリティ対策です。

また、JavaScript APIを通じて複数の属性に署名できるため、REST APIなど別の統合を使わずにMessenger経由でユーザー情報を安全に送信できます。

安全にデータを送信する利点を活用するために、不安全なMessenger更新から属性を保護し、JWTが送信されると安全なソースとみなしてそのフィールドを更新します。これは、Data connectorsが機密データを扱う場合やデータを操作する場合に重要です。

例えば、Data connectorが“GET /accounts/<account_id>/invoices”というAPIリクエストを行う場合、account_idが保護されていることを確認し、ユーザーが単にaccount_idを列挙してデータを収集できないようにします。しかし、“GET /pizza-order-status/<order_id>”の場合は、order_idの信頼性を気にせず、その情報が正しい人に表示されるかどうかも気にしないかもしれません。

さらに、Data connectorがユーザーを一意に識別するために使う属性（例えばメールアドレス）が信頼できることを確認すべきです。つまり、Data connectorの識別属性のソースを信頼している必要があります。例えば、Data connectorがuser_idでユーザーを識別する場合はuser_id属性に署名し、メールや他の属性で識別する場合はその属性が保護され、エンドユーザーからの検証なしに収集されないことを意味します。

これにより、悪意のある者が他人のメールアドレスを提供して「メールで銀行取引明細を取得」などのData connectorにアクセスし、機密の金融データを露出させることを防ぎます。

可能であれば、メールをユーザーのデータ取得の主な識別子として使わず、推測不可能な一意のユーザー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を一から構築する場合、次のいずれかの方法が考えられます。

1つのData connectorでWorkflowのビジネスロジックを処理できるようAPIを構築する方法 - これによりAPIコール数が削減され、ロジックが一箇所にまとめられます。
注文検索、注文詳細取得、注文の返金など個別のエンドポイントを構築する方法 - これはRESTful APIのベストプラクティスに沿っていますが、1つのWorkflow（例：注文返金）を完了するのに複数のAPIコールが必要です。

APIが返すデータの内容や量を決める際に考慮すべき点には以下があります。

Fin/WorkflowがWorkflowのステップを完了するために本当に必要なデータか？例えば、注文返金のWorkflowなら注文の詳細だけが必要で、特定ユーザーのアカウントに関する追加データは不要かもしれません。
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設計時に重要な違いです。

さらに、ユーザーが不正なデータを提供したり、自由入力することを常に防止すべきです。

例えば、ユーザーにアカウントIDを入力させるのではなく、既知の安全な識別子に基づくアカウントIDを提示し、ドロップダウンリストから選択させるべきです。ユーザーからのデータ収集方法の詳細はこちらをご覧ください。

その他の考慮事項

APIは、例えば1日あたりの返金上限など、アプリケーション固有の制限を強制すべきです。
Finは同じ返金リクエストを複数回送信する可能性があるため、APIは冪等性を確保してください。
サーバー側でのバリデーションを実装し、すべての入力がData connectorで指定された形式に準拠していることを確認してください。
AI生成フィールドに含まれる可能性のある幻覚や悪意のある内容を認識し、入力データのサニタイズを適用してください。
Finが適切に応答できるよう、標準的なHTTPエラーコードを使用してください。例えば、HTTP 429や500エラーは再試行が必要な場合があり、HTTP 410はこれ以上の試行を行わないことを示します。
APIのバージョン管理を行い、Live Fin Data connectorsのバージョン間移行（例：/v1/ordersから/v2/orders）を円滑にしてください。