钉钉用户同步
把钉钉作为用户数据源后，千问办公按所选范围读取部门和成员，并根据字段映射创建或更新用户。后续的入职、调岗和离职处理也由这份数据源配置控制。
一次性申请清单
将下表交给钉钉企业应用管理员，在「权限管理」中按名称查找并开通。先确定需要将哪些成员资料同步到千问办公，再申请对应权限。
| 权限或配置 | 是否需要 | 对应数据 |
|---|---|---|
| 通讯录部门信息读权限 | 必需 | 部门 ID、名称、上级关系 |
| 通讯录部门成员读权限 | 必需 | 部门中的成员列表 |
| 成员信息读权限 | 必需 | 成员标识、姓名、部门关系等基础资料 |
| 企业员工手机号信息 | 需要将手机号同步到千问办公时申请 | mobile |
| 邮箱等个人信息 | 需要将邮箱同步到千问办公时申请 | 核验成员详情中 org_email 等实际返回字段 |
| 成员信息读权限、通讯录部门成员读权限 | 工号随成员资料读取 | 钉钉成员接口返回 job_number，配置页对应 jobNumber；先确认成员档案已填写工号 |
| 通讯录权限范围、应用可见范围及发布 | 必需 | 覆盖目标部门、成员和必要的上级部门 |
请一次准备好以下信息：
- 企业与应用：企业名称、Corp ID、应用名称。
- 应用凭据：Client ID（AppKey）、Client Secret（AppSecret）。
- 权限与范围：权限开通结果、部门和成员范围；若平台要求，还需提供服务出口 IP。
- 测试资料：测试部门 ID、测试成员 unionId，以及预期同步的成员资料。
Corp ID 用于核对企业；本向导填写 Client ID 和 Client Secret。
先用测试部门执行一次同步，逐项对比人数、部门关系、三方 ID、邮箱、手机号、工号。连接成功只说明凭证与连接可用，不能替代通讯录权限和字段核验。同一应用承担 SSO 时，合并申请钉钉登录权限。
在钉钉开通通讯录读取
- 登录钉钉开放平台，进入 应用开发 → 企业内部开发，创建或打开企业内部应用。
- 打开 权限管理 → 通讯录管理。在搜索框依次查找并勾选 通讯录部门信息读权限、通讯录部门成员读权限、成员信息读权限。
- 若需要将钉钉成员的手机号同步到千问办公，则勾选 企业员工手机号信息。
- 若需要将钉钉成员的邮箱同步到千问办公，则勾选 邮箱等个人信息。
- 勾选所需权限后，点击【批量申请】。若同时同步手机号和邮箱，则应勾选第 2 步的三项基础权限，以及第 3、4 步的两项资料权限，共五项。
- 若需要将钉钉成员的工号同步到千问办公，则请通讯录管理员先在成员档案中填写工号，再在千问办公将 jobNumber 对应「工号」。工号随成员资料读取，使用第 2 步申请的权限。
- 在「权限范围」选择【全部员工】或【部分员工】。首次选测试部门，并包含测试成员及必要的上级部门；同时核对应用可见范围。
- 在「应用信息」取得 AppKey / Client ID 和 AppSecret / Client Secret。确认它们属于同一个应用。
- 若应用要求服务器出口 IP，填写千问办公同步服务的实际出口地址；完成权限审批、生效或应用发布流程。返回权限列表，确认上述申请已获授权。
权限开通后，请测试成员填好需要同步的资料，再执行一次同步。在千问办公「用户」页核对邮箱、手机号或工号是否与钉钉一致；若需要同步的资料为空，按下表处理。
| 缺少的资料 | 必须检查的项目 |
|---|---|
| 邮箱 | 「邮箱等个人信息」已获授权；测试成员的企业邮箱已填写；映射来源为 org_email |
| 手机号 | 「企业员工手机号信息」已获授权；成员档案有手机号；映射来源为 mobile |
| 工号 | 成员档案有工号；成员读取权限已获授权；映射来源为 jobNumber |
若三项均为空或成员没有导入，先检查应用权限范围是否包含该成员，再查看本次同步详情。不要只根据【测试连接】成功判断资料授权完成。
本接入向导提供手动和定时同步。无需为这两种方式配置钉钉事件订阅回调。
第一步：填写应用凭证
- 进入 用户与体验 → 用户管理 → 用户同步，点击【新增数据源】。
- 选择「钉钉」，点击【开始配置】。已有钉钉数据源时，点击该行【修改配置】。
- 将钉钉应用的 Client ID 和 Client Secret 填入同名字段。
- 点击【测试连接】检查连接，再点击【测试并下一步】进入映射设置。修改已有密钥时，只有输入新值才会替换原凭据。
【截图：管理后台钉钉数据源的 Client ID、Client Secret 和连接测试 · sync-dingtalk.png】
图 1：连接状态正常后，继续设置字段映射；此时还没有启动通讯录同步。
第二步：核对部门和成员映射
先检查部门，再检查成员。部门映射左侧来源和右侧目标字段固定；成员只有三方 ID、账号、工号可以选择来源字段。需要补充可选项时，从对应区域的【添加映射】下拉选择目标，页面带入钉钉预设字段，右侧目标字段加入后固定。下表用于核对钉钉返回的数据。
| 配置页预设的来源字段 | 千问办公字段 |
|---|---|
| 部门 id、name、parentId | 第三方部门 ID、部门名称、上级第三方部门 ID |
| 成员 unionId、name | 第三方用户 ID、用户姓名 |
| org_email、mobile、jobNumber | 邮箱、手机号、工号 |
| staffId、departmentId、active | 账号、所属部门的第三方部门 ID、用户状态 |
如果 SSO 同样使用钉钉，核对登录侧 user.unionId 与同步侧 unionId 能对应同一人。成员所属部门的 ID 必须能在部门映射结果中找到。
【截图：管理后台钉钉同步向导中的部门映射和成员映射 · sync-mapping.png】
图 2：第三方用户 ID、姓名和部门关系是核对重点；带星号的必填映射不能删除。
第三步：选择策略并执行同步
- 点击【下一步】，选择「全部组织」或指定部门范围。千问办公设置的范围还受钉钉应用读取权限限制。
- 设置「默认授予席位」。若希望先核对账号再分配席位，可保持关闭。
- 首次选择「手动同步」，设置 删除处理。通常先采用「停用账号并回收席位」，便于检查离职结果；是否直接删除应按企业账号保留要求决定。
- 设置删除告警阈值和告警邮箱，点击【保存配置】。
- 在数据源列表开启钉钉。企业同一时间只启用一个数据源；切换前核对提示中的原数据源。
- 点击【立即同步】，完成后在「同步记录」点击本次任务【详情】，核对新增、更新、停用、删除及席位变化。
- 在「用户」页核对测试成员和部门。结果正确后，再扩大范围或改为定时同步。
常见问题
| 现象 | 处理方法 |
|---|---|
| 连接正常但少了成员 | 检查钉钉应用的通讯录权限范围和千问办公同步范围，两者都须覆盖该成员 |
| 邮箱为空 | 检查 org_email 等实际资料字段及读取权限，不要用个人邮箱字段替代企业邮箱而不核对 |
| 同步部分成功 | 打开记录详情，根据失败对象和原因修正，再发起同步 |
| 大量成员被判定离职 | 先停用数据源，检查权限范围、映射和部门范围是否被缩小，再决定恢复与重试 |
删除告警用于提醒和记录，不等同于执行前审批。调整范围或删除策略前，应先估算会受影响的成员数量。
与已有用户衔接
同步前，先核对来源中的三方 ID 与已有用户一致。
- 匹配用户： 只通过三方 ID 查找。账号、邮箱、手机号和工号用于冲突校验；三方 ID 未命中，但其中任一值已被占用时，本条同步失败。
- 更新成功： 保留原 QID，并将当前维护来源设为这份数据源。
- 锁定资料： 来源开启期间，该来源用户的姓名、邮箱、账号、手机号、三方 ID、工号均不可手动修改；部门和状态按映射锁定。
- 恢复用户： 删除记录只能由已开启、且来源 ID 与记录一致的同步任务恢复。账号、邮箱、手机号或工号已被复用时，先修正来源数据，再重新同步。
修改映射、切换来源和恢复的完整规则见用户同步。