通讯录同步-企业微信
概述
适用场景
重要：由于企业微信通讯录集成规则限制了集成的 IP 地址及域名与企业微信组织是否一致，所以仅在私有化版本中使用，不建议在 SaaS 平台配置多个企业微信组织的通讯录同步。如 SaaS 平台需要配置，请提交工单获取专业支持。
前提条件
企业微信应用配置步骤
1.
2.
3.
4.
5.
操作步骤
步骤 1：创建同步任务
1.
2.
3.
4.
5.
步骤 2：配置目标连接
| 参数 | 说明 | 是否必填 |
|---|---|---|
| CorpID | 企业微信的企业 ID | 是 |
| AgentID | 自建应用的 AgentID | 是 |
| AppSecret | 自建应用的 Secret | 是 |
| 校验文件 | 从企业微信管理后台获取的网页授权校验文件 | 否（按需配置） |
提示：测试连接失败时，常见原因为 CorpID/Secret 错误、服务器 IP 未在可信列表中、或应用权限不足。请逐一排查。
步骤 3：配置字段映射
用户属性映射
| 平台属性 | 企业微信字段 | 数据类型 | 必填 | 建议映射方式 |
|---|---|---|---|---|
| sub（用户ID） | userid | String | 是 | 创建且更新 |
| name（姓名） | name | String | 是 | 创建且更新 |
| mobile（手机号） | mobile | String | 否 | 创建且更新 |
| email（邮箱） | String | 否 | 创建且更新 | |
| department_ids（部门） | department | Array | 是 | 创建且更新 |
| position（职位） | position | String | 否 | 创建且更新 |
| address（地址） | address | String | 否 | 创建且更新 |
| avatar（头像） | avatar | String | 否 | 创建且更新 |
注意：企业微信中手机号获取需要应用具有敏感信息权限，如平台用户手机号为空或权限不足，企业微信端手机号将不会更新。
部门属性映射
| 平台属性 | 企业微信字段 | 数据类型 | 必填 | 建议映射方式 |
|---|---|---|---|---|
| id（部门ID） | id | String | 是 | 创建且更新 |
| name（部门名称） | name | String | 是 | 创建且更新 |
| parent_id（父部门ID） | parentid | String | 是 | 创建且更新 |
| order（排序值） | order | Integer | 否 | 创建且更新 |
步骤 4：配置同步规则
| 参数 | 说明 | 建议配置 |
|---|---|---|
| 同步范围 | 同步内容类型：用户和部门 / 仅同步用户 | 选择「用户和部门」 |
| 根组织ID | 组织架构同步起始节点 | 全量填"1"，部分填具体部门 ID |
| 同步方式 | 自动增量 / 自动全量 / 手动全量 | 日常变更选「自动增量」，定期校验选「自动全量」 |
| 同步周期 | 执行同步的频率 | 建议"每小时"，稳定后"每6小时" |
| 开始时间 | 同步执行的起始时间 | 建议业务低峰期 |
| 强制创建 | 是否强制在下游创建 | 建议开启 |
| 删除用户阈值 | 触发删除保护的阈值 | 小型企业 8 |
注意：企业微信 API 有调用频率限制（每分钟最多 300 次），大型组织请合理设置同步周期，避免触发限流。
步骤 5：执行同步并验证
1.
2.
3.
验证与测试
连接测试
1.
2.
3.
同步结果验证清单
| 验证项 | 验证方法 | 预期结果 |
|---|---|---|
| 用户数量 | 对比平台与企业微信的用户数量 | 数量一致（排除不在同步范围） |
| 用户信息 | 抽查用户姓名、手机号、部门 | 与平台一致 |
| 组织结构 | 对比部门层级和数量 | 层级关系一致 |
| 增量变更 | 在平台修改用户信息后触发同步 | 变更在企业微信端生效 |
| 删除保护 | 删除超过阈值用户 | 用户进入待删除列表，非直接删除 |
同步日志查看
1.
2.
常见问题
Q1：测试连接报错"访问 IP 不在白名单中"
Q2：同步后用户在企业微信 中无手机号
1.
2.
3.
Q3：同步后组织架构层级不正确
1.
2.
3.
Q4：API 调用频率超限
1.
2.
3.
修改于 2026-05-06 10:16:33