企业微信通讯录
企业微信通讯录能力用于把企业微信的成员、部门和组织结构接入到产品中。它适合成员选择、部门权限、组织架构展示、身份映射和通知对象选择等场景。
适合什么场景
- 在产品中展示企业微信部门树。
- 根据部门或成员设置数据权限、审批人或负责人。
- 查询员工信息，用于任务分配、通知和组织协作。
- 将企业微信用户身份与产品账号对应起来。
接入前需要准备
| 准备项 | 说明 |
|---|
| 企业微信基础插件 | 企业微信通讯录依赖 企业微信插件。如果还没有配置，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 需要读取哪些部门、成员字段，以及这些数据用于哪些页面或流程。
发布后测试
使用已绑定的企业备案域名进行测试，确认部门和成员数据可以正常读取。
常见限制
- 企业微信要求域名备案主体与企业认证主体一致，开发预览域名通常无法通过安全校验。
- 应用可见范围不足时，可能只返回部分成员或部门。
- 通讯录字段读取遵循企业微信权限控制，敏感字段需要额外授权。
