> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/authorization-integration/vendor-integration-guide.md). # ソフトウェアベンダー統合ガイド（エンドツーエンド） 本ページは「MaiAgent Web Chat を自社プロダクトに埋め込み、自社のアカウントシステムと権限連携を行う」ソフトウェアベンダー向けです。ユーザーがお客様のシステムにログインすると、AI アシスタントがそのユーザーを認識し、会話履歴を遡ることができ、**そのユーザーの権限**でお客様のシステムの API を呼び出せるようになります。 連携の旅は全5段階で構成されています。本ページでは各段階で何をするか、どの順序で進めるかを説明し、詳細はそれぞれの技術ドキュメントへリンクしています。 ## 連携の全体像 ```mermaid flowchart LR subgraph ONCE["一度きりの構築"] A["Web Chat を埋め込む"] --> B["既存ユーザーを一括補完"] end subgraph DAILY["日常運用（アカウントライフサイクル）"] C["ユーザー新規追加時に連絡先を作成"] --> D["ログイン時に Token を更新"] D --> E["Token リフレッシュ時に再同期"] E --> F["ログアウト時に認証情報を無効化"] end ONCE --> DAILY ``` 核心的なコンセプトは1つだけです：**連絡先（Contact）**——お客様のシステムの各ユーザーが、MaiAgent の1つの連絡先に対応します。連絡先には会話履歴、パーソナライズ属性、ナレッジベースのクエリ範囲、ツール認証情報が紐付けられます。権限連携のすべてのアクションは、本質的には「お客様のユーザー ↔ 連絡先」という対応関係とその認証情報を維持することです。コンセプトの紹介は[連絡先（Contact）の紹介と連携](/tech/ja/authorization-integration/contacts.md)を参照してください。 ### フロントエンドとバックエンドの役割分担 連携の全工程において、お客様のフロントエンドは「チャットウィンドウの読み込み」のみを担当し、Token や API Key を伴うすべての呼び出しはお客様のバックエンドから発信します： ```mermaid flowchart LR subgraph FE["お客様のフロントエンド"] A["埋め込みコードで SDK を読み込み
config に contactId を含める"] B["ログアウト時に signOut を呼び出し"] end subgraph BE["お客様のバックエンド"] C["ログイン／リフレッシュ：POST setup-contact-credentials"] D["一括補完：POST bulk-import"] E["データ同期：PATCH contacts"] F["ログアウト：DELETE ツール認証情報"] end subgraph MA["MaiAgent"] G["チャットウィンドウ
chat.maiagent.ai"] H["API
api.maiagent.ai"] end A --> G B --> G C --> H D --> H E --> H F --> H ``` このうち `setup-contact-credentials` は API Key 不要（公開エンドポイント）です。`bulk-import`、`PATCH`、`DELETE` はすべて `Authorization: Api-Key` 認証が必要であり、バックエンドからのみ呼び出せます。 ## ステップ1：Web Chat を埋め込む プロダクトの形態に応じて埋め込み方法を選択してください。どちらも同じ SDK と同じ連絡先の仕組みを使用しています： | 形態 | 適したケース | ドキュメント | | ---------------------------------- | ------------------------- | ------------------------------------------------------------------------------- | | チャットバブル（floating／sidebar） | カスタマーサポート、問い合わせなどの補助機能 | [Web Chat 埋め込みと SDK](/tech/ja/api-integration/web-chat-sdk.md) | | MaiGPT モード（ChatGPT ライクなフルインターフェース） | ページのメイン機能エリア、サイト全体の AI 入口 | [MaiGPT モード埋め込み](/tech/ja/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) | {% hint style="info" %} ID 連携を行う Web Chat には、この時点で「許可された埋め込みドメイン」リストを設定することを推奨します（現在 MaiAgent チームがお客様のために設定します。ドメインリストを担当窓口にご提供ください）。ID 同期 API を呼び出せるソースを制限できます。[許可された埋め込みドメイン](/tech/ja/api-integration/web-chat-sdk.md#embed-origin-allowlist)を参照してください。 {% endhint %} ## ステップ2：初回連携——既存ユーザーの一括補完 既存システムの初回連携時に、現在のユーザーの連絡先を一括で補完します。2つの方法があります： | 方法 | 適したケース | ドキュメント | | ------------------------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **Excel 一括インポート**（`POST /contacts/bulk-import/`） | 大量のユーザー（1回あたり上限 10,000 行）。ナレッジクエリ範囲と API ツール認証情報も同時に取り込めます | [連絡先の一括インポート](/tech/ja/authorization-integration/contacts.md#bulk-import) | | **身元同期 API を1件ずつ呼び出し** | ログインフローに沿って段階的に補完する場合、または少量の場合 | [既存ユーザーの一括補完](/tech/ja/authorization-integration/contact-credentials-sync.md#backfill) | 補完時点でユーザーの Access Token が取得できなくても問題ありません。まず対応関係を作成し、Token 認証情報はステップ4のログインフローで各ユーザーの次回ログイン時に補完します。 ## ステップ3：ユーザー新規追加時に連絡先を作成 補完が完了したら、お客様のシステムの「アカウント作成」フローに API 呼び出しを1回追加します。新規ユーザーが登録された時点で対応する連絡先を作成します： * バックエンドで[身元同期 API（`setup-contact-credentials`）](/tech/ja/authorization-integration/contact-credentials-sync.md)を呼び出し、お客様のシステムのユーザー識別子を `sourceId` として指定します * 返却された `contactId` を会員データテーブルに保存します（推奨されるフィールド設計は[ログインフローの統合箇所](/tech/ja/authorization-integration/contact-credentials-sync.md#login-flow)を参照してください） `sourceId` は冪等キーです。同一の `sourceId` で重複呼び出ししても更新のみで、重複作成されません。そのため、このステップはステップ2およびステップ4と安全に共存できます。 ## ステップ4：ログインと Token リフレッシュ 毎回ログイン成功後、Access Token を生成してから、バックエンドで同じ身元同期 API をもう1回呼び出し、**新しい Token**（`mcpCredentials`）を渡します。これにより AI アシスタントがそのユーザーの身元と権限でお客様のシステムの API を呼び出せるようになります。Token リフレッシュ時も同じ方法です。もう1回呼び出すだけで、同一の（連絡先、ツール）の組み合わせでは更新となり、重複作成されません。完全なシーケンス図と注意事項（非同期呼び出し、失敗時にログインをブロックしない）は[連絡先の身元同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md)を参照してください。 フロントエンドでは、ページで Web Chat を初期化する際に `contactId` を指定します。[ユーザーの識別](/tech/ja/api-integration/web-chat-sdk.md#identify-users)を参照してください。 {% hint style="info" %} AI にお客様のシステムの API を呼び出させる必要がなく、ユーザーを識別するだけでよい場合は、バックエンドを経由せず、フロントエンドの config に `auth` を指定するだけで対応できます。選択の基準については[フロントエンド auth とバックエンド連携の選び方](/tech/ja/authorization-integration/contact-credentials-sync.md#frontend-vs-backend)を参照してください。 {% endhint %} ## ステップ5：ログアウトと認証情報の無効化 ログアウト時には2つの処理があり、作用範囲が異なるため、両方実施することを推奨します： * **フロントエンド**：SDK の `signOut()` を呼び出し、チャットウィンドウを匿名状態に戻します * **バックエンド**：該当連絡先のツール認証情報を削除し、AI が即座にそのユーザーの身元でツールを呼び出せないようにします 詳細な API と両者の違いの対照表は[ログアウトと認証情報の無効化](/tech/ja/authorization-integration/contact-credentials-sync.md#logout-revoke)を参照してください。 ## 連携チェックリスト | 段階 | アクション | ドキュメント | | -- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | 構築 | Web Chat を埋め込む（通常または MaiGPT モード） | [Web Chat 埋め込みと SDK](/tech/ja/api-integration/web-chat-sdk.md)／[MaiGPT モード](/tech/ja/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) | | 構築 | ドメインリストを MaiAgent に提供し「許可された埋め込みドメイン」を設定 | [許可された埋め込みドメイン](/tech/ja/api-integration/web-chat-sdk.md#embed-origin-allowlist) | | 構築 | 会員データテーブルに `maiagent_contact_id` フィールドを追加 | [ログインフローの統合箇所](/tech/ja/authorization-integration/contact-credentials-sync.md#login-flow) | | 構築 | 既存ユーザーを一括補完 | [連絡先の一括インポート](/tech/ja/authorization-integration/contacts.md#bulk-import) | | 運用 | アカウント作成フローで身元同期 API を呼び出し | [連絡先の身元同期と Token 更新](/tech/ja/authorization-integration/contact-credentials-sync.md) | | 運用 | ログイン／Token リフレッシュフローで認証情報を更新 | [呼び出しタイミング](/tech/ja/authorization-integration/contact-credentials-sync.md#when-to-call) | | 運用 | ログアウトフローで認証情報を無効化 | [ログアウトと認証情報の無効化](/tech/ja/authorization-integration/contact-credentials-sync.md#logout-revoke) | | 高度 | 部門、会員ランクなどのパーソナライズ属性を同期 | [連絡先情報の同期](/tech/ja/authorization-integration/contact-credentials-sync.md#sync-contact-profile) | | 高度 | クエリメタデータで各ユーザーのナレッジベース検索範囲を制限 | [ナレッジ管理権限（Query Metadata）](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/tech/ja/authorization-integration/vendor-integration-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.