通讯录同步-用友U8C

本文介绍如何配置集成平台与用友U8C的通讯录同步，将平台中的组织架构和用户信息自动推送至用友U8C系统，实现企业身份数据的统一管理。

概述

集成平台支持将用户数据和组织架构自动推送到用友U8C，降低管理成本，确保各系统间身份信息实时同步。

数据自动推送

按设定周期自动推送数据至用友U8C，无需人工干预

身份统一管理

集中管理各系统账号，实现「一处变更，处处生效」

数据一致性保障

确保各系统间身份数据保持同步，避免信息孤岛

安全机制保障

内置删除阈值机制，防止数据异常造成大规模用户误删

适用场景

场景	说明
多系统身份打通	企业同时使用用友U8C与其他应用系统，需统一管理用户身份
组织架构权限分配	将企业组织架构同步至用友U8C，用于自动化权限分配
员工入离职自动化	新员工入职或离职时，自动在用友U8C中创建或删除账号
财务人员集中管理	集中管理财务系统的用户账号，确保安全性和合规性

前提条件

已获取用友U8C的管理员账号和密码（需具备 API 访问权限）

已获取用友U8C的服务器地址、系统编码等配置参数

已获取用友U8C的根组织 ID（通常为 1）

拥有集成平台的管理员权限

集成平台服务器可访问用友U8C系统 API 接口

获取系统参数

登录用友U8C系统后，从系统管理模块获取系统编码，从组织架构管理模块获取根组织 ID。

所需 API 权限

权限名称	权限代码	用途	必需
用户管理权限	`user.manage`	创建、修改、删除用户	是
组织结构管理权限	`org.manage`	创建、修改、删除组织结构	是
数据查询权限	`data.read`	读取系统数据	是
系统配置权限	`config.manage`	修改系统配置	否

操作步骤

步骤 1：创建同步连接器

登录集成平台管理控制台

在左侧导航栏选择 用户中心 → 通讯录同步

点击页面右上角的「添加连接器」按钮

在弹出的平台选择面板中，选择「用友U8C」图标

图 1：创建用友U8C同步连接器

步骤 2：填写基本连接信息

参数名称	说明	填写指南
连接器名称	连接器显示名称	建议使用有业务含义的名称，如「财务部U8C同步」
服务器地址	用友U8C的服务器访问地址	企业内部服务器地址
系统编码	用友U8C的系统编码	从系统管理模块获取
用户名	管理员账号	需具备 API 管理权限
管理员密码	对应密码	-
根组织ID	组织架构根节点 ID	全部部门信息填写 `1`

步骤 3：配置同步策略

根据业务需求选择同步方式，详见下方「同步方式对比」。

参数名称	说明	建议配置
同步方式	指定同步方式	初始选择「手动全量」，稳定后切换「自动增量」
同步周期	自动同步频率	初始设置「手动」，稳定后设置为 1-6 小时
删除用户阈值	触发删除保护的阈值	小型企业 8-10%，中型 5-8%，大型 3-5%

提示：自动增量同步模式不显示删除用户阈值；手动全量同步模式不显示同步周期设置。

步骤 4：配置属性映射

配置平台与用友U8C之间的用户和部门属性对应关系，详见下方「属性映射配置」章节。

图 2：属性映射配置界面

步骤 5：测试连接并保存

点击右上角的「测试连接」按钮，验证配置信息是否正确

测试成功后，点击「保存并同步」按钮触发首次同步

在通讯录同步列表页观察同步状态和进度

同步方式对比

自动增量同步

适用日常运维，只同步变更数据，资源消耗少，同步速度快。

自动全量同步

适用定期校验，同步所有数据，可纠正历史错误，确保一致性。

手动全量同步

适用初始化和大规模变更，需手动触发，灵活控制同步时机。

删除用户阈值说明

📌

删除用户阈值是一项安全机制。当需要删除的用户数量占总用户数的比例超过阈值时，系统会将这些用户放入「待删除用户」列表，而非直接删除。

计算公式：删除阈值(%) = (待删除用户数 / 总用户数) x 100%

企业规模	建议阈值	原因
小型（`<500` 用户）	8-10%	用户基数小，少量变动导致较高比例变化
中型（500-2000 用户）	5-8%	组织相对稳定，可有效防止异常删除
大型（`>2000` 用户）	3-5%	用户数量多，较低阈值更好保护数据安全

属性映射配置

属性映射是将集成平台中的用户/部门属性与用友U8C中的属性建立对应关系的过程。

映射方式说明

映射方式	说明	适用场景
不映射	该属性不会被同步到用友U8C	无需在用友U8C中展示的内部属性
仅创建	只在创建时同步，更新时不同步	初始化后不应被自动更新的属性，如员工编号
创建和更新	创建和更新时均同步	需保持实时同步的核心属性，如姓名、手机号

用户属性映射

平台属性	用友U8C属性	数据类型	必填	建议映射方式
`sub`	`user_id`	String	是	创建和更新
`name`	`user_name`	String	是	创建和更新
`mobile`	`mobile`	String	是	创建和更新
`email`	`email`	String	否	创建和更新
`employee_number`	`emp_code`	String	否	仅创建
`position`	`position`	String	否	创建和更新
`department_ids`	`dept_ids`	Array	否	创建和更新
`manager_id`	`manager_id`	String	否	创建和更新

部门属性映射

平台属性	用友U8C属性	数据类型	必填	建议映射方式
`id`	`dept_id`	String	是	创建和更新
`name`	`dept_name`	String	是	创建和更新
`parent_id`	`parent_id`	String	是	创建和更新
`order`	`display_order`	Integer	否	创建和更新
`code`	`dept_code`	String	否	创建和更新

验证与测试

验证项	验证方法	预期结果
连接测试	点击「测试连接」按钮	提示「连接成功」
首次同步	点击「保存并同步」或「立即同步」	状态显示「同步成功」，日志无错误
用户数据	登录用友U8C检查测试账号	姓名、手机号等关键属性同步正确
组织架构	在用友U8C中查看部门结构	部门层级和名称与平台一致
增量同步	在平台新增/修改用户后触发同步	变更数据正确同步至用友U8C

增量同步测试方法

在平台中执行以下测试变更：新增测试用户、修改已同步用户信息、移动用户部门、创建新部门

手动触发同步或等待自动同步周期

在用友U8C中验证所有变更是否正确生效

同步日志解读

访问路径：在通讯录同步列表页，点击目标连接器的「日志」按钮

日志信息	含义
开始同步数据	同步操作已启动
获取源数据成功	成功从平台获取源数据
创建/更新/删除对象成功	对应操作已成功完成
同步完成	整个同步过程结束
错误：xxx	操作失败，后跟具体错误信息

待删除用户管理

当同步过程中检测到需删除的用户超过阈值时，这些用户会被放入「待删除用户」列表，需管理员审核确认后才会在下次同步中执行删除。

访问路径：用户中心 → 通讯录同步 → 找到目标连接器 → 点击「待删除用户」

待删除用户信息

信息项	说明
用户基本信息	用户姓名、工号、部门、手机号等
删除原因	「源数据不存在」「不在同步范围」「数据不完整」等
待删除时间	用户被标记为待删除状态的时间

处理操作

操作	说明
确认删除	点击「确认删除」，用户将在下次同步时从用友U8C中删除
批量确认删除	选中多个用户后点击「批量确认删除」
拒绝删除	点击「拒绝删除」，用户从待删除列表移除，保持现有状态

注意

批量删除前务必仔细核对用户列表，确保不会误删重要账号。

常见问题

Q：连接测试提示「连接失败」？

Q：连接测试提示「认证失败」？

Q：同步完成但部分用户数据不正确？

Q：同步失败，提示数据格式错误？

Q：部分用户同步失败，提示用户冲突？

Q：组织架构层级不匹配怎么办？

Q：无法修改或删除用友U8C中的用户？

错误代码参考

错误代码	描述	解决方案
`401`	未授权	检查并更正认证信息
`403`	禁止访问	使用具有足够权限的账号
`404`	未找到资源	检查服务器地址和 API 路径
`500`	内部服务器错误	检查日志，联系系统管理员
`1001`	用户名已存在	修改用户名或使用更新操作
`1002`	无效的组织 ID	使用有效的组织 ID
`1003`	数据格式错误	按正确格式修改数据
`1004`	缺少必填字段	补充所有必填字段

最佳实践

初始配置建议

推荐：先在测试环境验证配置，选择小型部门进行初始同步，逐步扩大范围

不推荐：直接在生产环境进行首次全量同步

准备工作：梳理组织架构，清理源数据，获取必要权限，制定回滚方案

测试环境验证：在测试环境完成配置并验证数据正确性

小范围试运行：选择一个小型部门进行生产环境同步测试

逐步扩大范围：验证成功后逐步扩大同步范围

配置自动同步：全部验证通过后，开启自动增量同步

运维监控建议

频率	检查项
每日	检查同步状态，确保按计划执行且成功完成
每周	检查同步日志和待删除用户列表
每月	执行一次全量同步，确保数据一致性；抽样对比数据
每季度	检查和优化配置参数；审查同步账号权限

性能优化

日常使用增量同步，降低系统负载；定期执行全量同步确保一致性

只同步需要的用户和部门，使用根组织 ID 限定同步范围

错开不同系统的同步时间，避免资源竞争

在网络高峰期避开同步操作

应用场景参考

场景 1：财务部门与 HR 系统集成

场景 2：全公司账号统一管理

场景 3：项目团队临时账号管理

附录

用友U8C用户字段规格

字段名	数据类型	长度限制	必填	说明	格式要求
`user_id`	String	最大 50 字符	是	用户唯一标识	企业内唯一
`user_name`	String	最大 100 字符	是	用户姓名	不能包含特殊字符
`mobile`	String	11-20 字符	是	手机号	标准手机号格式
`email`	String	最大 100 字符	否	电子邮箱	标准邮箱格式
`emp_code`	String	最大 50 字符	否	员工编号	企业内唯一
`position`	String	最大 100 字符	否	职位	无特殊要求
`dept_ids`	Array	-	否	所属部门 ID 列表	部门 ID 数组
`manager_id`	String	最大 50 字符	否	直属上级 ID	必须是有效的用户 ID
`status`	Integer	-	否	用户状态	`0`-禁用，`1`-启用
`user_type`	Integer	-	否	用户类型	`0`-普通用户，`1`-管理员

用友U8C部门字段规格

字段名	数据类型	长度限制	必填	说明	格式要求
`dept_id`	String	最大 50 字符	是	部门 ID	企业内唯一
`dept_name`	String	最大 100 字符	是	部门名称	同级部门不能重复
`parent_id`	String	最大 50 字符	是	父部门 ID	必须是有效的部门 ID
`display_order`	Integer	-	否	部门排序	正整数
`dept_code`	String	最大 50 字符	否	部门编码	企业内唯一
`manager_id`	String	最大 50 字符	否	部门负责人 ID	必须是有效的用户 ID
`is_hidden`	Boolean	-	否	是否隐藏部门	`true`-隐藏，`false`-显示

系统要求

类别	要求
用友U8C版本	V13.0 及以上
集成平台版本	2.5 及以上
网络延迟	不超过 500 毫秒
操作系统	Windows Server 2012 及以上

概述#

适用场景#

前提条件#

所需 API 权限#

操作步骤#

同步方式对比#

删除用户阈值说明#

属性映射配置#

映射方式说明#

用户属性映射#

部门属性映射#

验证与测试#

增量同步测试方法#

同步日志解读#

待删除用户管理#

待删除用户信息#

处理操作#

常见问题#

错误代码参考#

最佳实践#

初始配置建议#

运维监控建议#

性能优化#

应用场景参考#

附录#

用友U8C用户字段规格#

用友U8C部门字段规格#

系统要求#

概述

适用场景

前提条件

所需 API 权限

操作步骤

同步方式对比

删除用户阈值说明

属性映射配置

映射方式说明

用户属性映射

部门属性映射

验证与测试

增量同步测试方法

同步日志解读

待删除用户管理

待删除用户信息

处理操作

常见问题

错误代码参考

最佳实践

初始配置建议

运维监控建议

性能优化

应用场景参考

附录

用友U8C用户字段规格

用友U8C部门字段规格

系统要求