> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 企業微信自建應用後台配置指南
> 在企業微信管理後台建立自建應用、配置應用能力與回調 URL 的完整步驟說明，為後續 OAuth 登入、訊息接收等整合做準備。
## 概述
本指南說明如何在企業微信管理後台完成自建應用的建立與基礎配置。自建應用是企業微信整合的起點，後續無論是網頁授權登入（如掃碼登入）、接收成員訊息、發送應用訊息等，都需要先在後台完成應用建立、能力開通與回調設定。完成本指南後，您將取得 **CorpID**、**AgentID**、**Secret** 等關鍵參數，並完成回調 URL 的驗證，為後續整合步驟做好準備。
## 背景
開始配置前，請確認已具備以下前提條件：
* **完成企業認證的企業微信帳號**：需以企業管理員身份登入 [企業微信管理後台](https://work.weixin.qq.com/wework_admin/frame#/apps)
* **企業微信後台管理員權限**：需有權限建立自建應用、配置開發者介面
* **已完成 ICP 備案的域名**：且備案主體須與企業微信認證的企業主體相同，否則無法通過域名校驗
## 企微後台配置
### 建立企業自建應用
1. 開啟 [企業微信管理介面](https://work.weixin.qq.com/wework_admin/frame#/apps)，登入後點擊應用管理
2. 點擊「**自建**」，注意選擇**部門/成員**，這個控制了哪些用戶可以看到
### 配置域名
企業微信對回調域名有嚴格的備案要求，配置前請確認以下兩點：
**要求一：必須使用已備案域名**
域名必須完成 ICP 備案，且**備案主體須與企業微信認證的企業主體相同，或具有關聯關係**。
> 例如：企業微信後台認證的是 B 公司，但域名備案主體是 A 公司，則無法通過驗證。域名備案主體必須是 B 公司。
參考：[企業內部開發配置域名指引](https://open.work.weixin.qq.com/wwopen/common/readDocument/40754)
**要求二：不能使用 superun 提供的預設域名**
以下域名的備案主體為 superun（杭州優勢智設科技有限公司），與您企業的認證主體不同，**無法**用作企業微信回調域名：
* `*.superun.app`（如 `name.superun.app`、`id-idvalue.superun.app`）
* `*.superun.yun`（如 `name.superun.yun`、`id-idvalue.superun.yun`）
請使用您企業自有的、已完成備案的域名進行配置。
> **測試說明**：以下示例使用 superun（杭州優勢智設科技有限公司）的企業微信進行測試開發。由於 `superun.yun` 域名的備案主體與該企業微信主體相同，因此可直接用於配置。
### 配置網頁授權及JS-SDK
> 用於**靜默授權模式**：在企微內建瀏覽器中透過 OAuth2 URL 跳轉自動完成登入，需在此處設定可信域名。
**步驟 1：下載域名校驗檔案**
1. 進入應用詳情頁，點擊「**開發者介面**」
2. 點擊「**網頁授權及JS-SDK**」，在彈窗中點擊「**申請校驗域名**」
3. 下載校驗檔案，記錄檔案名稱與檔案內容
**步驟 2：在 superun 中部署校驗檔案**
在 superun 的聊天介面中，輸入以下 prompt（將 `<文件名>` 和 `<文件內容>` 替換為實際下載的內容），然後等待開發完成：
```
在 public 目錄下建立一個檔案，名字為 <文件名>.txt，內容為 <文件內容>
```
**步驟 3：發布應用並綁定自訂域名**
1. 進入 superun「**營運 → 發布**」介面，確認應用已上線
2. 進入 superun「**營運 → 搜尋優化**」，配置您已備案的自訂域名
**步驟 4：在企業微信後台填寫可信域名**
回到企業微信管理後台，在「網頁授權及JS-SDK」中填寫您的自訂域名作為可信域名。
> ⚠️ **注意**：截圖中填寫的是 `hello-world2504.superun.yun`，這是因為該測試應用所屬的企業微信主體與 `superun.yun` 的備案主體相同，所以才能直接使用。**您必須填寫自己企業備案的域名**，不能照搬截圖中的域名。
### 配置企業微信授權登入
> 用於**掃碼模式**：在外部瀏覽器中透過企微 JS-SDK 掃碼面板完成登入，需在此處設定授權回調域。
1. 進入應用詳情頁，「**開發者介面**」
2. 點擊「**企業微信授權登入**」，在Web網頁授權回調頁中填寫您的備案自訂域名
### 企業可信 IP
企業微信要求所有呼叫其介面的請求必須來自**固定 IP**，並事先加入企業可信 IP 白名單。參考：[開發前必讀 - 可信 IP](https://developer.work.weixin.qq.com/document/path/90664)
**問題**：Supabase Edge Function 的出口 IP 不固定，無法直接加入白名單。
**解決方案**：使用 superun 提供的固定 IP 代理轉發功能（或自行搭建類似轉發服務），詳見[固定 IP 代理轉發方案](/superun/skills/proxy-forward)。
**配置步驟**：
1. 進入應用詳情頁，「**開發者介面**」
2. 找到「**企業可信 IP**」，填入以下兩個固定 IP：
```
43.153.29.204;43.153.7.159
```
## 取得關鍵參數
完成以上配置後，需記錄以下三個關鍵參數，後續對接時會用到：
**CorpID（企業 ID）**
1. 進入企業微信管理後台，點擊左側「**我的企業**」
2. 頁面底部可找到「企業 ID」，即 CorpID(WECOM\_CORP\_ID)
**AgentID（應用 ID）與 Secret（應用密鑰）**
1. 進入「**應用管理**」，點擊對應的自建應用
2. 頁面中可直接看到 **AgentID**，(WECOM\_AGENT\_ID)
3. 點擊「**查看**」取得 **Secret**，Secret(WECOM\_SECRET) 會發送到管理員手機端，需在企業微信 App 中查看
> ⚠️ **注意**：Secret 只能透過手機端查看，請妥善保存，勿洩露。
## 測試說明
在 superun 的開發介面中進行除錯時，頁面運行在 superun 平台自身的域名下（如 `*.superun.app`），而企業微信要求網頁授權回調域、JS-SDK 可信域名等必須是**企業微信認證主體名下已備案的域名**。由於 superun 的域名備案主體與您的企業微信主體不同，開發階段的預覽地址無法通過企業微信的域名校驗，OAuth 回調、JS-SDK 鑑權等功能將無法正常運作。
因此，**必須先將應用發布上線，並綁定您企業自有的已備案域名後，再進行企業微信相關功能的測試**。