修改员工基本信息

基本信息

权限标识 | employee:basic:info:update

请求参数

顶层字段

字段名	类型	必填	说明
`corpId`	string	✅	企业ID
`empId`	string	✅	需要修改的员工ID
`data`	`Map<string, BasicInfoFieldValue>`	✅	待修改的基本信息，key为字段编码

BasicInfoFieldValue 的可用类型：

string | number | string[]

实际类型由字段元数据中的 fieldType 和 multiSelect 决定：

字段类型	BasicInfoFieldValue实际类型
文本、日期、单选等单值字段	`string`
数字	`number`，也兼容可转换为数字的 `string`
多选、地址	`string[]`

data（基本信息）

data 为平铺的动态 Map，不需要再嵌套 basicInfo。以下为当前接口支持更新的系统基本信息字段：

字段名	类型	必填	说明
`name`	string	按企业配置	姓名
`employeeNumber`	string	按企业配置	工号
`mobileNumber`	string	按企业配置	手机号码，需符合手机号格式
`idType`	string	按企业配置	证件类型，传选项编码
`idNumber`	string	按企业配置	证件号码
`idName`	string	❌	证件姓名
`validPeriodOfId`	string	❌	证件有效期，格式 `yyyy-MM-dd`
`idAddress`	string	❌	证件地址
`dateOfBirth`	string	❌	出生日期，格式 `yyyy-MM-dd`
`ethnicity`	string	❌	民族，传选项编码
`gender`	string	❌	性别，传选项编码
`nativeRegion`	string	❌	籍贯
`currentResidentialAddress`	string	❌	现居住地址
`maritalStatus`	string	❌	婚姻状况，传选项编码
`politicalStatus`	string	❌	政治面貌，传选项编码
`hukouType`	string	❌	户口类型，传选项编码
`hukouLocation`	`string[]`	❌	户口所在地行政区编码数组
`dateEnteredWorkforce`	string	❌	参加工作日期，格式 `yyyy-MM-dd`
`email`	string	❌	工作邮箱
`personalEmail`	string	❌	个人邮箱
`socialSecurityAccount`	string	❌	社保账号
`providentFundAccount`	string	❌	公积金账号
`{customFieldId}`	`BasicInfoFieldValue`	按企业配置	企业自定义基本信息字段

字段必填规则、字段类型和选项值以 /open/api/v1/employee/roster/meta 返回的 basicInfo 分组元数据为准。

以下字段不能通过本接口修改：

字段	原因
`age`	自动计算字段
`workSeniorityAge`	自动计算字段
`dingMobileNumber`	系统维护字段
附件类型字段	当前接口不支持附件上传或更新
任职信息、任职状态等其他分组字段	本接口只处理 `basicInfo` 分组

请求示例

{
  "corpId": "ding4c7c311a701851ac35c2f4657eb6378f",
  "empId": "emp_3be55bc703ee4c02910d5def3b00b60d",
  "data": {
    "field_emp_stri_032": "123",
    "field_emp_numb_007": "456",
    "field_emp_date_009": "2024-12-11",
    "field_emp_sele_020": "selection_2c8ab81930f94371a2f46ba9f78570ab",
    "field_emp_sele_021": [
      "selection_4010c28527684fc29229262975c477dc",
      "selection_cf31f97413734cf7bdbc2f579ffd2ee8",
      "selection_1f2e7ba14c2f473ca30205e269d906ef"
    ],
    "field_emp_addr_003": [
      "11",
      "1101",
      "110101"
    ]
  }
}

示例动态字段类型：

字段名	字段类型	请求值类型
`field_emp_stri_032`	文本	`string`
`field_emp_numb_007`	数字	可转换为数字的 `string`
`field_emp_date_009`	日期	`yyyy-MM-dd` 格式的 `string`
`field_emp_sele_020`	单选	选项编码 `string`
`field_emp_sele_021`	多选	选项编码 `string[]`
`field_emp_addr_003`	地址	行政区编码 `string[]`

响应参数

通用响应字段

字段名	类型	说明
`success`	boolean	外层请求处理结果；字段校验失败时仍可能为 `true`
`errorCode`	`string \| null`	全局错误码
`errorMsg`	`string \| null`	成功提示或全局错误信息
`rid`	`string \| null`	链路追踪ID，部分环境返回
`data`	`Map<string, string> \| null`	字段校验结果；key为字段编码，value为错误信息

本接口没有 validateResult 字段。字段校验错误直接返回在外层响应的 data Map 中。

响应示例

修改成功

修改成功时，data 为 null，成功信息在 errorMsg 中：

{
  "data": null,
  "success": true,
  "errorCode": null,
  "errorMsg": "修改成功"
}

字段校验失败

HTTP 状态码通常仍为 200，且外层 success=true；data 非空表示字段校验未通过。

{
  "data": {
    "mobileNumber": "手机号码格式错误",
    "email": "邮箱格式错误"
  },
  "success": true,
  "errorCode": null,
  "errorMsg": null
}

员工不存在

{
  "data": null,
  "success": false,
  "errorCode": "404",
  "errorMsg": "该员工不存在"
}

更新规则

局部更新：只更新 data 中传入且属于基本信息分组的字段，未传字段保持原值。

null值处理：字段值为 null 时不会更新该字段，也不能通过传 null 清空字段。

空Map处理：data={} 可以通过顶层非空校验，但不会修改任何业务字段，请至少传入一个需要更新的字段。

动态字段：自定义字段直接平铺在 data 中，key使用字段元数据中的 fieldId。

未知字段：不在当前企业花名册字段元数据中的字段不会落库。

自动字段：age、workSeniorityAge、dingMobileNumber 即使传入也不会更新。

其他分组：workInfo、workStatusInfo 等非基本信息字段即使放入 data 也不会通过本接口更新。

钉钉同步：基本信息保存成功后，系统会触发员工人事信息同步到钉钉。

成功判断

本接口的成功判断与新增人员入职花名册接口不同：

success == true
AND data 为空
AND errorMsg == "修改成功"

如果 success=true 但 data 非空，表示字段校验失败，不应提示修改成功。

注意事项

接口权限：调用方的 OAuth2 Token 必须具备 employee:basic:info:update scope。

员工归属：empId 必须属于 corpId 对应企业，否则返回员工不存在。

字段元数据：调用前建议通过 POST /open/api/v1/employee/roster/meta 获取字段编码、类型、必填规则和选项值。

日期格式：日期字段统一使用 yyyy-MM-dd 格式。

选项字段：单选传选项编码字符串，多选传选项编码数组，不要传选项展示文案。

地址字段：传行政区编码数组，例如 ["11", "1101"]。

附件字段：当前接口不支持附件上传或更新，请勿传入附件字段。

字段清空：当前接口不支持使用 null 清空字段；需要清空字段时应先确认具体字段是否允许传空字符串或空数组。

异常重试：网络超时或响应结果不明确时，先调用 POST /open/api/v1/employee/detail 确认字段是否已经更新，再决定是否重试。

修改员工基本信息

修改员工基本信息

基本信息

请求参数

顶层字段

data（基本信息）

请求示例

响应参数

通用响应字段

响应示例

修改成功

字段校验失败

员工不存在

更新规则

成功判断

注意事项

请求参数

请求示例代码

返回响应

修改员工基本信息

修改员工基本信息#

基本信息#

请求参数#

顶层字段#

data（基本信息）#

请求示例#

响应参数#

通用响应字段#

响应示例#

修改成功#

字段校验失败#

员工不存在#

更新规则#

成功判断#

注意事项#

请求参数

请求示例代码

返回响应

修改员工基本信息

基本信息

请求参数

顶层字段

data（基本信息）

请求示例

响应参数

通用响应字段

响应示例

修改成功

字段校验失败

员工不存在

更新规则

成功判断

注意事项