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