企业微信用户同步
将企业微信设为数据源后，千问办公读取自建应用授权范围内的部门和成员。企业 ID 决定读取哪个企业，Agent ID 与 Secret 决定使用哪个应用及其可读取范围。
一次性申请清单
企业微信按应用授权和可见范围限制通讯录读取。请应用管理员核对以下能力；权限名称以当前企业微信后台显示为准。
| 权限或配置 | 是否需要 | 需要核对的内容 |
|---|---|---|
| 自建应用管理权限 | 必需 | 能取得并维护本应用的 Agent ID 和 Secret |
| 可见范围内的部门读取 | 必需 | 返回部门 ID、名称、上级部门 ID；范围包含必要的上级部门 |
| 可见范围内的成员及成员详情读取 | 必需 | 返回 userid、姓名、部门关系和可用的状态资料 |
| 邮箱、手机号等敏感资料可读取 | 需要将邮箱或手机号同步到千问办公时核验 | 同时检查应用资格、授权条件及实际接口返回值 |
| 应用可见范围 | 必需 | 覆盖拟同步部门和成员，首次先纳入测试范围 |
| 企业可信 IP | 平台要求时必需 | 包含千问办公同步服务的实际出口 IP |
请一次准备好以下信息：
- 企业与应用：企业名称、Corp ID、应用名称、Agent ID、同一应用的 Secret。
- 访问范围：部门及成员可见范围、服务出口 IP。
- 测试资料：测试部门 ID、测试成员 userid，以及预期同步的成员资料。
若同一应用还提供扫码登录，请一并完成企业微信 SSO 清单中的回调和域名配置；仅做通讯录同步无需填写 SSO 回调。
新建自建应用通过通讯录接口获取手机号、邮箱等敏感信息受到企业微信限制；成员已填写资料、管理员已扩大可见范围，也不代表这些字段会返回。先执行一次测试部门同步，检查部门、人数、用户标识和每个选用字段。若缺少敏感资料，请与企业微信管理员确认可行的授权和资料维护方式，不要通过反复扩大权限范围来代替核验。
准备企业微信通讯录权限
- 登录企业微信管理后台，在「我的企业」取得 企业 ID（Corp ID）。
- 打开 应用管理 → 应用 中用于千问办公的自建应用，记录 AgentId 和该应用的 Secret。
- 在应用详情的「可见范围」加入测试部门及成员。打开「授权信息」，确认成员、部门的读取能力已获授权；如页面按「成员信息」和「部门信息」分别列出，请逐项确认。
- 若需要将企业微信成员的手机号同步到千问办公，则请应用管理员确认应用具有手机号读取资格和授权，再用测试成员执行一次同步。
- 若需要将企业微信成员的邮箱同步到千问办公，则请应用管理员确认应用具有邮箱读取资格和授权，再用测试成员执行一次同步。成员基本信息授权不代表手机号、邮箱均可读取。
- 如果企业微信要求「企业可信 IP」，添加千问办公同步服务访问企业微信接口的固定出口 IP。
- 核对测试成员的企业微信账号、邮箱、手机号和部门资料。确认记录的 Secret 属于该应用，而不是其他应用或其他用途的凭据。
创建数据源并测试连接
- 在千问办公进入 用户与体验 → 用户管理 → 用户同步，点击【新增数据源】。
- 选择「企业微信」，点击【开始配置】。
- 在 Corp ID 填写企业 ID，在 Agent ID 填写应用 AgentId，在 Secret 填写应用密钥。
- 点击【测试连接】，连接正常后点击【测试并下一步】。
【截图：管理后台企业微信数据源的 Corp ID、Agent ID 和 Secret · sync-wecom.png】
图 1：企业 ID 与应用凭证分开填写；测试连接通过后再检查通讯录字段。
检查用户与部门映射
企业微信的用户唯一标识使用 userid，部门唯一标识使用部门的 id。在映射步骤中核对下列关系；只有三方 ID、账号、工号可以选择来源字段。其他成员字段及部门字段固定。需要新增可选映射时，打开该区域的【添加映射】下拉选择目标，右侧字段加入后不能更改。
| 来源字段 | 千问办公字段 |
|---|---|
| 用户 userid | 第三方用户 ID，默认也作为账号字段来源 |
| 用户 name、email、mobile | 用户姓名、邮箱、手机号 |
| 用户 department、status | 所属部门的第三方部门 ID、用户状态 |
| 部门 id、name、parentid | 第三方部门 ID、部门名称、上级第三方部门 ID |
一个成员属于多个部门时，检查其部门关系是否完整。若同时启用企业微信 SSO，登录侧的 user.userid 应与同步侧 userid 对应同一个人。
保存策略并运行首轮同步
- 点击【下一步】，选择同步范围。先用可明确核对的部门验证，再扩大到全部组织。
- 选择是否默认授予席位，首次将「同步方式」设为「手动同步」。
- 根据企业离职要求设置「删除处理」，配置告警阈值和告警邮箱，点击【保存配置】。
- 启用企业微信数据源。若已有数据源启用，确认切换后原数据源停止生效。
- 点击【立即同步】，在「同步记录」打开本次任务【详情】，核对创建、更新、停用和删除人数。
- 到「用户」页面检查一名新成员、一名多部门成员及其席位状态。稳定后可改为每天或每 6 小时定时同步。
出错时从哪里查
| 现象 | 优先处理 |
|---|---|
| 企业微信拒绝接口请求 | 检查 Corp ID、Agent ID、Secret 的归属，及可信 IP 配置 |
| 只同步到应用创建者 | 检查应用可见范围和通讯录读取权限 |
| 某成员缺邮箱或手机号 | 核对源资料及接口可读取字段，不要用姓名匹配不同成员 |
| 调岗后部门不正确 | 检查 department 与部门 id 的对应关系，查看记录详情中的部门增减 |
不要用登录成功判断同步成功。登录依赖认证配置，用户同步需要另外核验任务记录和用户列表。
与已有用户衔接
同步前，先核对来源中的三方 ID 与已有用户一致。
- 匹配用户： 只通过三方 ID 查找。账号、邮箱、手机号和工号用于冲突校验；三方 ID 未命中，但其中任一值已被占用时，本条同步失败。
- 更新成功： 保留原 QID，并将当前维护来源设为这份数据源。
- 锁定资料： 来源开启期间，该来源用户的姓名、邮箱、账号、手机号、三方 ID、工号均不可手动修改；部门和状态按映射锁定。
- 恢复用户： 删除记录只能由已开启、且来源 ID 与记录一致的同步任务恢复。账号、邮箱、手机号或工号已被复用时，先修正来源数据，再重新同步。
修改映射、切换来源和恢复的完整规则见用户同步。