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