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