> ## 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.

# 企業微信通訊錄

> 在 superun 中接入企業微信成員查詢、部門樹、組織架構和身份映射能力。

# 企業微信通訊錄

企業微信通訊錄能力用於把企業微信的成員、部門和組織結構接入到產品中。它適合成員選擇、部門權限、組織架構展示、身份映射和通知對象選擇等場景。

***

## 適合什麼場景

* 在產品中展示企業微信部門樹。
* 根據部門或成員設定數據權限、審批人或負責人。
* 查詢員工資訊，用於任務分配、通知和組織協作。
* 將企業微信用戶身份與產品帳號對應起來。

***

## 接入前需要準備

| 準備項      | 說明                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| 企業微信基礎插件 | 企業微信通訊錄依賴 [企業微信插件](/zh-Hant/superun/integrations/wecom)。如果還沒有配置，superun 會在接入過程中引導你填寫 CorpID、AgentID 和 Secret |
| 後台配置指南   | 如果還沒有建立自建應用，先參考 [企業微信自建應用後台配置指南](/zh-Hant/superun/skills/wecom/wecom-self-built-app-setup)                   |
| 通訊錄權限    | 在企業微信管理後台為自建應用開通通訊錄讀取權限                                                                                      |
| 應用可見範圍   | 確認應用可見範圍覆蓋目標部門和成員                                                                                            |
| 網域和可信 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`       | 通訊錄權限 + 應用可見範圍 |

<Warning>
  如果接口返回 `60011`，通常是自建應用沒有通訊錄權限，或可見範圍沒有覆蓋目標部門/成員。請先在企業微信後台檢查權限和可見範圍。
</Warning>

***

## 如何在 superun 中啟用

<Steps>
  <Step title="點擊「企業微信通訊錄」">
    在「研發」→「技能庫」中打開「企業微信通訊錄」，點擊使用，並說明產品裡需要使用成員、部門或身份映射的業務場景。
  </Step>

  <Step title="按引導完成基礎配置">
    如果專案還沒有配置企業微信基礎插件，對話框會引導你填寫 CorpID、AgentID 和 Secret；如果已經配置過，會直接複用已有配置。
  </Step>

  <Step title="開通通訊錄權限">
    按照 [企業微信自建應用後台配置指南](/zh-Hant/superun/skills/wecom/wecom-self-built-app-setup)，在企業微信後台確認自建應用擁有通訊錄讀取權限，並設定應用可見範圍。
  </Step>

  <Step title="補充數據範圍">
    告訴 superun 需要讀取哪些部門、成員欄位，以及這些數據用於哪些頁面或流程。
  </Step>

  <Step title="發佈後測試">
    使用已綁定的企業備案網域進行測試，確認部門和成員數據可以正常讀取。
  </Step>
</Steps>

***

## 常見限制

* 企業微信要求網域備案主體與企業認證主體一致，開發預覽網域通常無法通過安全校驗。
* 應用可見範圍不足時，可能只返回部分成員或部門。
* 通訊錄欄位讀取遵循企業微信權限控制，敏感欄位需要額外授權。