企業微信通訊錄
企業微信通訊錄能力用於把企業微信的成員、部門和組織結構接入到產品中。它適合成員選擇、部門權限、組織架構展示、身份映射和通知對象選擇等場景。
適合什麼場景
- 在產品中展示企業微信部門樹。
- 根據部門或成員設定數據權限、審批人或負責人。
- 查詢員工資訊，用於任務分配、通知和組織協作。
- 將企業微信用戶身份與產品帳號對應起來。
接入前需要準備
| 準備項 | 說明 |
|---|
| 企業微信基礎插件 | 企業微信通訊錄依賴 企業微信插件。如果還沒有配置，superun 會在接入過程中引導你填寫 CorpID、AgentID 和 Secret |
| 後台配置指南 | 如果還沒有建立自建應用，先參考 企業微信自建應用後台配置指南 |
| 通訊錄權限 | 在企業微信管理後台為自建應用開通通訊錄讀取權限 |
| 應用可見範圍 | 確認應用可見範圍覆蓋目標部門和成員 |
| 網域和可信 IP | 企業微信對網域、備案主體和可信 IP 有安全校驗要求 |
企業微信後台需要配置什麼
企業微信通訊錄不像飛書那樣透過一組固定 scope key 批量導入。這裡主要配置的是自建應用的通訊錄權限、應用可見範圍和接口調用安全項。
| 配置項 | 在哪裡配置 | 用途 |
|---|
| 通訊錄權限 | 企業微信管理後台 → 應用管理 → 自建應用 → 權限或接口權限相關區域 | 允許自建應用讀取部門和成員資訊 |
| 應用可見範圍 | 企業微信管理後台 → 自建應用 → 可見範圍 | 決定應用可以訪問哪些部門和成員 |
| CorpID | 企業微信管理後台 → 我的企業 | 企業 ID，用於識別企業 |
| AgentID | 自建應用詳情頁 | 應用 ID，用於登入和應用訊息等場景 |
| Secret | 自建應用詳情頁 | 應用密鑰，用於取得企業微信 access_token |
| 可信網域 / 授權回呼網域 | 自建應用詳情頁 | 用於企業微信 OAuth 登入或網頁授權 |
| 可信 IP | 自建應用詳情頁 | 企業微信接口調用的來源 IP 白名單 |
| 能力 | 企業微信接口 | 需要的後台配置 |
|---|
| 獲取部門列表 | /cgi-bin/department/list | 通訊錄權限 + 應用可見範圍 |
| 獲取子部門 ID | /cgi-bin/department/simplelist | 通訊錄權限 + 應用可見範圍 |
| 獲取部門成員詳情 | /cgi-bin/user/list | 通訊錄權限 + 應用可見範圍 |
| 讀取單個成員 | /cgi-bin/user/get | 通訊錄權限 + 應用可見範圍 |
| 獲取部門成員簡要資訊 | /cgi-bin/user/simplelist | 通訊錄權限 + 應用可見範圍 |
如果接口返回 60011，通常是自建應用沒有通訊錄權限，或可見範圍沒有覆蓋目標部門/成員。請先在企業微信後台檢查權限和可見範圍。
如何在 superun 中啟用
點擊「企業微信通訊錄」
在「研發」→「技能庫」中打開「企業微信通訊錄」，點擊使用，並說明產品裡需要使用成員、部門或身份映射的業務場景。
按引導完成基礎配置
如果專案還沒有配置企業微信基礎插件，對話框會引導你填寫 CorpID、AgentID 和 Secret；如果已經配置過，會直接複用已有配置。
補充數據範圍
告訴 superun 需要讀取哪些部門、成員欄位，以及這些數據用於哪些頁面或流程。
發佈後測試
使用已綁定的企業備案網域進行測試，確認部門和成員數據可以正常讀取。
常見限制
- 企業微信要求網域備案主體與企業認證主體一致，開發預覽網域通常無法通過安全校驗。
- 應用可見範圍不足時，可能只返回部分成員或部門。
- 通訊錄欄位讀取遵循企業微信權限控制，敏感欄位需要額外授權。
