企业微信插件
本指南使用企业微信自建应用，需要企业管理员管理应用、可见范围、域名和可信 IP。不要使用群机器人 Webhook，也不要将通讯录同步助手的 Secret 填成自建应用的 Secret。
1. 创建应用并记录凭据
- 登录企业微信管理后台，在 应用管理 → 自建 创建应用
- 在 我的企业 → 企业信息 复制 企业 ID（CorpId）
- 在自建应用详情复制 AgentId 和该应用的 Secret
- 设置 应用可见范围，包含需要读取、登录或接收通知的成员与部门；需要完整部门树时，按后台允许的范围授权整个企业
企业微信自建应用不采用飞书的 contact:* 或钉钉的 qyapi_* 权限编码。可调用能力由应用类型、当前 Secret、应用可见范围、企业设置及接口规则共同决定。
| 功能 | 企业微信侧需要准备的设置 | 插件实际接口 |
|---|---|---|
| 部门与成员 | 自建应用的部门、成员读取能力及可见范围，服务器可信 IP | /cgi-bin/department/list、/cgi-bin/user/list |
| 判断完整部门范围 | 应用详情读取能力；可见范围包含根部门 | /cgi-bin/agent/get |
| 个人应用消息 | 当前自建应用的 AgentId、Secret，接收人可见范围，服务器可信 IP | /cgi-bin/message/send |
| 授权登录 | 网页授权可信域名，应用主页入口，邮箱等成员敏感信息授权 | 网页授权及 /cgi-bin/auth/getuserinfo、/cgi-bin/user/get、/cgi-bin/auth/getuserdetail |
上表服务端接口位于 https://qyapi.weixin.qq.com。组织同步只修改 Soln 数据，不需要写入企业微信通讯录。
2. 准备 HTTPS 域名和校验文件
需要一个成员设备及企业微信可访问的租户 HTTPS 地址，例如 https://workspace.example.com。本地开发可使用固定 HTTPS 隧道域名，并满足企业微信对域名及验证的要求。
- 在自建应用的 网页授权及 JS-SDK 配置中下载域名校验文件，名称类似
WW_verify_abcdef.txt - 保留文件名和文件中的原始文本，安装插件时分别填写 可信域名校验文件名、可信域名校验文件内容
- 插件启用后，检查
https://workspace.example.com/WW_verify_abcdef.txt可直接返回原文，不应返回登录页或前端 HTML - 回到企业微信后台完成域名验证并保存
如果后台在验证通过前允许先下载文件，先下载并安装，再返回完成验证。校验文件由插件配置提供，无需把文件上传到业务表单或手动写进前端目录。
3. 安装 Soln 插件
- 打开 集成 → 应用 → 插件，安装企业微信插件
- 填写 企业 ID、AgentId、应用 Secret、可信域名校验文件名及内容
- 身份映射方式通常选 匹配租户内启用成员的邮箱；如果选 显式邮箱白名单，还需填写白名单，白名单本身不会创建成员
- 启用后进入 应用信息，复制 身份提供方重定向 URL 和 单点登录入口地址
4. 分别配置域名、入口与可信 IP
这些设置用途不同，需要分别完成：
| 设置 | 填写位置和格式 | 示例 |
|---|---|---|
| 网页授权可信域名 | 自建应用 → 网页授权及 JS-SDK → 设置可信域名；填写域名，按后台要求验证 | workspace.example.com |
| Web 授权回调域 | 开通 企业微信授权登录 → Web 网页 时，设置授权回调域；此处填域名，不是完整回调路径 | workspace.example.com |
| 应用主页 / 桌面端主页 | 填 Soln 的 单点登录入口地址，保留完整 URL 和查询参数 | 从 Soln 复制，不手工拼接 |
| 企业可信 IP | 自建应用中的 企业可信 IP；填写实际请求企业微信接口的服务器公网出口 IP | 公网 IPv4，例如 203.0.113.10 仅作格式示例，不可照填 |
Soln 展示的回调可能是 https://workspace.example.com/plugins/wecom/callback。企业微信要求“可信域名”或“授权回调域”的输入框只填其中的 workspace.example.com；完整 URL 由登录协议使用，不要把它填成应用主页。
本地部署如何确定可信 IP
在运行租户插件的机器上查询公网出口，例如：
curl -4 https://api.ipify.org
如果插件通过 Docker、代理、VPN、NAT 或服务器中转访问企业微信，应确认插件实际请求的出口，并与企业微信报错返回的 IP 核对。宿主机上浏览器或命令行的出口可能与插件不同。
可信 IP 不填 127.0.0.1、192.168.*、10.* 等本机或内网地址，也不填隧道域名、域名解析 IP 或隧道入口服务器 IP，除非该服务器确实同时承载了插件请求的出口。公网出口变化后需要更新此项。
5. 获取通讯录
在插件 组织映射 点击 获取通讯录，分别查看组织、部门和用户。只有组织记录，没有部门或用户，不代表整个通讯录已经获取成功，需要继续检查应用可见范围、应用 Secret 和接口错误。
成员邮箱、企业邮箱和手机号等字段可能受平台限制而不通过普通通讯录接口返回。管理员扩大可见范围，不等于成员已授权读取敏感信息；不要仅因为邮箱列为空就反复更换 Secret 或把同名成员自动绑定。
6. 用授权登录自动补充成员绑定
不方便由管理员逐个整理几百位成员的对应关系时，可以让成员通过企业微信登录一次，由系统补充已确认身份的绑定。
- 在自建应用的 成员敏感信息授权 中启用实际可申请的 邮箱 和 企业邮箱 权限，并按后台要求生效
- 在企业微信成员资料中填写邮箱，并确保它与 Soln 内启用成员的邮箱一致；需要先在 Soln 创建或导入成员
- 确认 账户中心 → 单点登录 的企业微信连接已启用，应用主页已配置为 Soln 的单点登录入口
- 成员从企业微信客户端打开该应用，按授权页面确认提供邮箱等信息。插件使用
snsapi_privateinfo，需要平台返回敏感信息访问凭证user_ticket - 登录成功并解析到对应 Soln 成员后，系统为该 CorpId 下的
userid补充插件用户绑定；有已获授权的邮箱时，也会补充到通讯录快照 - 管理员回到 组织映射 → 用户 刷新列表，检查绑定，再验证个人消息推送
每次成功登录都会检查绑定，只补缺失项，不会每次重建，也不会覆盖已有的冲突绑定。一个成员已绑定其他外部账号，或同一个 userid 已绑定其他成员时，需要管理员核实处理。
此流程不会自动创建 Soln 成员，也不能绕过席位与成员启用规则。登录时没有邮箱、没有 user_ticket 或邮箱无法匹配启用成员时，先修正授权和资料。普通微信账号、非企业成员或不支持该授权的入口不能代替这条企业微信成员授权链路。
7. 配置消息推送与组织同步
| 需要的功能 | 操作 |
|---|---|
| 只推送审批、任务及普通提醒 | 完成有效成员绑定后，进入 消息推送 → 推送配置，新增业务应用、选择模板、保存并启用 |
| 同步组织架构 | 获取通讯录、核对已有对象绑定，在 同步组织架构 配置字段映射后单独启用 |
| 处理外部删除的部门 | 在同步弹窗底部选择保留、停用或删除；只有确认完整企业部门范围时才执行缺失部门处理 |
消息使用插件已配置的 AgentId 和 Secret，无需在推送配置再填钉钉 AgentId。当前发送应用文本卡片与 Soln 详情入口，不创建企业微信原生审批实例。
完整操作和同步席位规则见企业身份插件使用指南。
企业微信列表中的字段怎么读
固定列、搜索、分页、下载、自动绑定和消息日志的逐项操作见企业身份插件列表与操作说明。外部返回字段受应用权限、成员授权及资料完整性限制。
组织与部门列表
| 列表或字段 | 含义与值 |
|---|---|
组织的外部 ID / corpid | 当前企业 CorpId；与部门根 ID 1 不同，组织记录本身不证明已读取到部门和成员 |
| 组织名称 | 可以读取根部门时使用其名称，否则可能显示企业 CorpId |
部门的 id / parentid | 部门 ID / 上级部门 ID；根部门通常为 1，父级 0 表示平台根层级 |
name / name_en | 部门名称 / 英文名，不是两个部门 |
department_leader | 部门负责人用户 ID 数组，不会自动赋予 Soln 权限 |
order | 部门同级排序，不是成员数量 |
用户列表
| 字段编码 | 含义与值 |
|---|---|
userid / open_userid | 企业内用户 ID / 服务商范围用户 ID；当前绑定与应用消息使用 userid |
name / alias / english_name | 姓名 / 别名 / 英文名，不能只按同名认定身份 |
department / main_department | 所属部门 ID 数组 / 主部门 ID，可能与内部成员当前部门不同 |
order / is_leader_in_dept | 对应部门的排序 / 负责人标记；后者 1 是、0 否，按所属部门数组的顺序对应 |
status | 1 已激活、2 已禁用、4 未激活、5 退出企业；这是企业微信状态，不是绑定状态或 Soln 席位状态 |
email / biz_mail | 邮箱 / 企业邮箱；普通接口可能为空，授权登录获取邮箱后可补充快照及用户绑定 |
mobile / telephone | 手机 / 座机，是否返回取决于接口与授权 |
gender | 0 未定义、1 男、2 女 |
position / direct_leader | 职务 / 直属上级 userid 列表 |
avatar / thumb_avatar | 头像 / 缩略图 URL，列表展示地址 |
address / qr_code | 地址 / 个人二维码地址，受平台返回范围限制 |
extattr.attrs | 成员自定义属性数组，每项包含名称、类型和值 |
extattr.attrs[].type | 0 文本、1 网页；文本看 text.value，网页看 web.url 与 web.title |
external_position / external_profile | 对外职务 / 对外资料，不等于内部组织权限 |
external_profile.external_corp_name | 对外企业简称 |
external_profile.external_attr | 对外扩展属性；type 为 0 文本、1 网页、2 小程序，按类型查看对应内容 |
external_profile.wechat_channels | 视频号属性；status 为 0 已确认、可正常使用，1 待确认，不是账号启用状态 |
例如“绑定方式”为“自动匹配”而邮箱列曾为空，可能是成员完成企业微信授权登录后补充了绑定，不能据此认为普通通讯录接口已经具备获取所有成员邮箱的权限。可点 查看 核对当前 userid、绑定成员与邮箱。
消息日志中的平台消息 ID 来自发送应用消息的返回；若显示“接收用户不可用”，先对照用户列表里的 userid、绑定有效性及应用可见范围，再检查可信 IP 和 Secret，不应改成 open_userid 尝试。
常见问题
| 现象 | 处理 |
|---|---|
| 当前出口 IP 不在允许范围 | 从插件实际网络路径确认公网出口，将其加入当前自建应用的可信 IP；不要只检查隧道域名 |
| 获取到了组织，但没有部门和用户 | 检查可见范围、应用 Secret、企业成员资料与具体接口错误；组织记录的 CorpId 不证明成员读取已成功 |
| 通讯录没有邮箱 | 普通接口可能不返回敏感字段；配置成员敏感信息授权，让成员完成一次授权登录 |
登录缺少 user_ticket | 检查敏感信息授权、网页授权可信域名、成员是否确认授权，以及是否从支持该流程的企业微信入口发起 |
| 已授权但不能匹配 Soln 成员 | 检查返回的邮箱与启用成员邮箱是否一致，是否使用正确 CorpId，以及现有身份或用户绑定是否冲突 |
| 消息失败或成员不可用 | 检查当前应用的 userid 绑定、可见范围、AgentId/Secret 和可信 IP；不要使用另一个企业的 userid |
| 校验文件打开成登录页 | 检查租户域名入口、代理路由以及插件校验文件配置，确保根路径可返回原文 |
| 更换隧道后失败 | 更新租户外部地址、可信域名、Web 授权回调域及应用主页；只有实际出口同时改变时才更新可信 IP |