> ## 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 中接入企业微信成员查询、部门树、组织架构和身份映射能力。

# 企业微信通讯录

企业微信通讯录能力用于把企业微信的成员、部门和组织结构接入到产品中。它适合成员选择、部门权限、组织架构展示、身份映射和通知对象选择等场景。

***

## 适合什么场景

* 在产品中展示企业微信部门树。
* 根据部门或成员设置数据权限、审批人或负责人。
* 查询员工信息，用于任务分配、通知和组织协作。
* 将企业微信用户身份与产品账号对应起来。

***

## 接入前需要准备

| 准备项      | 说明                                                                                                   |
| -------- | ---------------------------------------------------------------------------------------------------- |
| 企业微信基础插件 | 企业微信通讯录依赖 [企业微信插件](/superun/integrations/wecom)。如果还没有配置，superun 会在接入过程中引导你填写 CorpID、AgentID 和 Secret |
| 后台配置指南   | 如果还没有创建自建应用，先参考 [企业微信自建应用后台配置指南](/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="开通通讯录权限">
    按照 [企业微信自建应用后台配置指南](/superun/skills/wecom/wecom-self-built-app-setup)，在企业微信后台确认自建应用拥有通讯录读取权限，并设置应用可见范围。
  </Step>

  <Step title="补充数据范围">
    告诉 superun 需要读取哪些部门、成员字段，以及这些数据用于哪些页面或流程。
  </Step>

  <Step title="发布后测试">
    使用已绑定的企业备案域名进行测试，确认部门和成员数据可以正常读取。
  </Step>
</Steps>

***

## 常见限制

* 企业微信要求域名备案主体与企业认证主体一致，开发预览域名通常无法通过安全校验。
* 应用可见范围不足时，可能只返回部分成员或部门。
* 通讯录字段读取遵循企业微信权限控制，敏感字段需要额外授权。