人员同步接口
- 接口:第三方提供
- Method:POST
- 数据格式:JSON
- 接口说明:该接口用于同步员工信息到第三方
- 请求中的
data 为本次需要同步的人员列表;除 userNo、fullName、isLeave 等字段外,其余可选字段是否传递取决于云简侧的渠道配置
- 本接口的请求不携带 sign,鉴权仅使用
account + sessionId
- 文档末尾有文档版本记录
参数:
请求参数
| 字段名称 |
字段类型 |
字段描述 |
是否必填 |
| userNo |
String |
对接关键字,预留字段,当前版本不传递,人员以 data 中的 userNo 为准 |
N |
| account |
String |
公司账户 |
Y |
| sessionId |
String |
会话标识 |
Y |
| data |
List<UserInfo> |
数据 |
Y |
UserInfo
| 字段名称 |
字段类型 |
字段描述 |
是否必填 |
| userId |
Integer |
云简的用户编号,公司内唯一(优先传userNo,个别旧项目传userId,userId和userNo二选一) |
N |
| userNo |
String |
对接的用户编号,公司内唯一 |
Y |
| employNumber |
String |
员工工号 |
N |
| departmentName |
String |
部门名字 |
N |
| departmentCode |
String |
部门编码 |
N |
| costCenterName |
String |
成本中心名字 |
N |
| costCenterCode |
String |
成本中心代码 |
N |
| branchName |
String |
分公司名字 |
N |
| branchCode |
String |
分公司代码 |
N |
| parentUserNo |
String |
上级代码(由云简侧的模板映射产生,模板未配置时不传递) |
N |
| parentUserName |
String |
上级名字(由云简侧的模板映射产生,模板未配置时不传递) |
N |
| gender |
String |
性别, 标准值列表-附录19 |
N |
| mobile |
String |
手机号,会做校验,不合法的手机号是不会同步的。 |
N |
| emailAddress |
String |
邮件地址,存在没有邮箱或者假邮箱的公司 |
N |
| level |
String |
职级代码(实际管控依据),取云简职级配置的 level |
N |
| levelName |
String |
职级名字(只用于展示,有变更的可能),当前版本不传递 |
N |
| levelCode |
String |
取云简职级配置的 description |
N |
| isLeave |
Boolean |
true为离职,false为在职 |
Y |
| birthday |
String |
出生日期yyyy-MM-DD |
N |
| nationality |
String |
国籍,三字码,例如中国CHN |
N |
| fullName |
String |
姓名字 |
Y |
| surname |
String |
英文姓 |
N |
| givenName |
String |
英文名 |
N |
| extraInfo |
JSONObject |
扩展信息,当前版本不传递 |
N |
| cardInfo |
List<cardInfo> |
证件信息(基于个人信息保护法,原则上不传该部分) |
N |
| baseCity |
Integer |
城市编号(云简的城市编号) |
N |
| baseCityName |
String |
城市名称 |
N |
| regulationCodes |
List<String> |
制度code列表,是否传递取决于云简侧的渠道配置 |
N |
| userType |
String |
员工标识,通过此字段可实现各类员工有不同商旅权限,是否传递取决于云简侧的渠道配置 |
N |
cardInfo
| 字段名称 |
字段类型 |
字段描述 |
是否必填 |
| cardType |
String |
证件类型(取云简证件记录的 cardType,以字符串形式传递) |
Y |
| cardTypeId |
Integer |
云简证件记录编号(cardId) |
Y |
| cardNo |
String |
证件号码 |
Y |
| expirationDate |
long |
证件失效日期,13位时间戳,当前版本不传递 |
N |
| givenName |
String |
证件名,当前版本不传递 |
N |
| surname |
String |
证件姓,当前版本不传递 |
N |
返回参数
| 字段名称 |
字段类型 |
字段描述 |
是否必填 |
| resCode |
Integer |
错误码,正确填10000 |
Y |
| resMsg |
String |
错误描述,正确写success |
Y |
| data |
List<UserInfo> |
批量中,失败的用户必须需要返回,成功的可以不返回 |
Y |
UserInfo
| 字段 |
类型 |
释义 |
必填 |
| userId |
Integer |
云简的用户编号(优先返回userNo,个别旧项目可以返回userId,userId和userNo二选一) |
Y |
| userNo |
String |
对接的用户编号,公司内唯一,请求信息中传过去的值 |
Y |
| bindId |
String |
商旅平台用户的主键 |
Y |
| companyId |
Integer |
云简的公司编号(云简侧不解析) |
N |
| isLeave |
Boolean |
是否离职,Y时代表员工禁用(云简侧不解析) |
N |
| description |
String |
失败必填,成功可不填 |
Y |
| status |
Integer |
0是失败,1 是成功 |
Y |
说明:
- 云简按返回项中的
userNo 与请求中的人员匹配,status=0 的人员会被标记为同步失败并记录 description。
- 整体
resCode 不为 10000 时,云简会把本批人员全部标记为同步失败,并将 resMsg 记为失败原因。
示例:
请求数据
{
"account": "avcsd123",
"sessionId": "121312",
"data": [
{
"userNo": "91228",
"employNumber": "E1001",
"fullName": "测试",
"gender": "M",
"mobile": "12345678901",
"emailAddress": "test@qq.com",
"departmentCode": "01",
"departmentName": "test",
"costCenterCode": "01",
"costCenterName": "test",
"branchCode": "01",
"branchName": "test",
"level": "ES",
"levelCode": "专家",
"isLeave": false,
"birthday": "1997-11-10",
"nationality": "CHN",
"baseCity": 1,
"baseCityName": "上海",
"cardInfo": [
{
"cardType": "1",
"cardTypeId": 1,
"cardNo": "12312312"
}
]
}
]
}
返回数据
{
"resCode": 10000,
"resMsg": "部分员工同步失败",
"data": [
{
"userNo": "91228",
"status": 0,
"bindId": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
"description": "职级未维护,同步失败"
}
]
}
{
"resCode": 10000,
"resMsg": "同步成功",
"data": []
}
文档版本记录
| 版本号 |
编写日期 |
更改内容 |
| V1.0 |
2020.02.01 |
初稿 |
| V1.1 |
2020.09.27 |
修正level的定义为职级代码,去掉levelCode字段,新增levelName字段 |
| V1.2 |
2022.06.01 |
将userId一类的系统内部ID调整为可以公开的对接key,比如userId调整为userNo,companyId调整为account |
| V1.3 |
2022.10.18 |
同步返回结果中增加bindId |
| V1.4 |
2024.05.20 |
增加扩展字段extraInfo |
| V1.5 |
2025.10.22 |
增加员工base地字段 |
| V1.6 |
2025.10.28 |
增加员工regulationCodes,userType字段 |
| V1.7 |
2026.09.11 |
按当前实现修正:请求以 account + sessionId + data 提交,顶层 userNo 当前不传递;补充 employNumber;修正 baseCity 类型为 Integer;标注当前不传递的字段(levelName、extraInfo、cardInfo 的失效日期/姓名);补充结果匹配规则 |