飞书开放平台 Server API 文档

主题

更新任职信息 ​

默认为新增一条任职记录，包括职务、职级、序列、部门等信息。

Error: - 本接口不再推荐使用（历史问题较多），请使用以下接口（对齐业务、功能完善）

Warning: - 此接口默认缺乏业务校验，使用 strict_verify=true，相当于【人事系统-异动无审批】

  • 应用业务校验、发送异动事件、新增任职记录
  • 在【修改工时制度】、【插入任职记录】等场景下请检查异动管理
  • 「任职原因」不允许填写为「onboarding」或「offboarding」
  • 当上一个任职版本的「任职原因」为「onboarding」时，「任职原因」必填
  • 该接口默认是新增一条任职记录，并非原地编辑

Tip: - 非必填字段，如无特殊说明，不传时即不做变更

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/job_datas/:job_data_id
HTTP MethodPATCH
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:corehr 更新核心人事信息 corehr:job_data:write 读写任职信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 corehr:employment.pathway:read 获取员工通道信息 corehr:employment.pathway:write 读写员工通道 contact:user.employee_id:readonly 获取用户 user ID corehr:job_data.compensation_type:read 获取薪资类型 corehr:job_data.service_company:read 获取任职公司 corehr:job_data.work_shift:read 获取排班信息

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
job_data_idstring任职信息ID
示例值："151515"

查询参数 ​

名称类型必填描述
client_tokenstring否操作的唯一标识，用于幂等的进行更新操作，格式为标准的 UUIDV4。此值为空表示将发起一次新的请求，此值非空表示幂等的进行更新操作。
示例值："fe599b60-450f-46ff-b2ef-9f6675625b97"
user_id_typestring否用户 ID 类型
示例值：people_corehr_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？ - people_corehr_id: 以飞书人事的 ID 来识别用户
默认值：people_corehr_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
department_id_typestring否此次调用中使用的部门 ID 类型
示例值：open_department_id
可选值有：
- open_department_id: 【飞书】用来在具体某个应用中标识一个部门，同一个 department_id 在不同应用中的 open_department_id 相同。 - department_id: 【飞书】用来标识租户内一个唯一的部门。 - people_corehr_department_id: 【飞书人事】用来标识「飞书人事」中的部门。
默认值：people_corehr_department_id
strict_verifystring否是否强校验。值为 true 时，会对入参进行业务校验，并产生异动记录、发送异动事件。 - 默认值：true - 仅在新增任职版本时生效，即当 version_id 有值时该字段不生效 - 使用此功能时，试用期相关字段不支持 - 当响应返回的任职数据无变化时，请检查人事系统-异动管理
示例值：false

请求体 ​

名称类型必填描述
version_idstring否任职记录版本 ID - ID 不为空时，将更新指定版本的任职记录内容 - ID 为空时，将新增一个版本
功能灰度中，若需要更新指定版本请联系技术支持
示例值："6890452208593372697"
job_level_idstring否职务级别 ID，枚举值及详细信息可通过【批量查询职级】接口查询获得
示例值："6890452208593372679"
job_grade_idstring否职等 ID，枚举值及详细信息可通过【查询职等】接口查询获得
示例值："6890452208593372679"
employee_type_idstring否人员类型 ID，枚举值及详细信息可通过【批量查询人员类型】接口查询获得
示例值："6890452208593372679"
working_hours_type_idstring否工时制度 ID，枚举值及详细信息可通过【批量查询工时制度】接口查询获得
示例值："6890452208593372679"
work_location_idstring否工作地点 ID，枚举值及详细信息可通过【批量查询地点】接口查询获得
示例值："6890452208593372679"
department_idstring否部门 ID，枚举值及详细信息可通过【批量查询部门】接口查询获得 - 与 department_id_type 类型一致
示例值："6890452208593372679"
job_idstring否职务 ID，枚举值及详细信息可通过【批量查询职务】接口查询获得
示例值："6890452208593372679"
probation_start_datestring否试用期开始日期 - strict_verify 为 true 时不支持该字段
示例值："2018-03-16"
probation_end_datestring否试用期结束日期（实际结束日期） - strict_verify 为 true 时不支持该字段
示例值："2019-05-24"
primary_job_databoolean否是否为主任职 - 该字段已废弃，默认为 true，不可更改
示例值：true
effective_timestring否生效时间 - 不可为空字符，不传时默认值为当天
示例值："2020-05-01 00:00:00"
expiration_timestring否失效时间 - strict_verify 为 true 时不支持该字段
示例值："2020-05-02 00:00:00"
job_family_idstring否职务序列 ID，枚举值及详细信息可通过【批量查询序列】接口查询获得
示例值："1245678"
assignment_start_reasonenum否业务类型（原：任职原因） - 枚举值【获取字段详情】 - object_api_name: job_data - custom_api_name: assignment_start_reason - 请注意，该枚举不允许填写为「onboarding、offboarding」，当上一个任职版本的值为「onboarding」时，该字段必填
示例值：onboarding
  └ enum_namestring是枚举值
示例值："job_status_change"
probation_expected_end_datestring否预计试用期结束日期 - strict_verify 为 true 时不支持该字段
示例值："2006-01-02"
direct_manager_idstring否直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
示例值："6890452208593372679"
dotted_line_manager_id_liststring\[\]否虚线上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
示例值：["6890452208593372681"]
second_direct_manager_idstring否第二直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得 - strict_verify 为 true 时不支持该字段
示例值："6890452208593372679"
cost_center_ratesupport_cost_center_item\[\]否成本中心分摊信息
- 当 version_id 有值时，不支持该字段
  └ cost_center_idstring否支持的成本中心 ID，详细信息可通过【搜索成本中心信息】接口查询获得
示例值："6950635856373745165"
  └ rateint否分摊比例
示例值：100
work_shiftenum否排班类型，枚举值 api_name 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "job_data" - custom_api_name = "work_shift"
  └ enum_namestring是枚举值。需自定义
示例值："example"
compensation_typeenum否薪资类型，枚举值 api_name 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "job_data" - custom_api_name = "compensation_type"
  └ enum_namestring是枚举值。需自定义
示例值："example"
service_companystring否任职公司 ID，详细信息可通过【批量查询公司】接口查询获得
示例值："6890452208593372680"
pathway_idstring否通道 ID
示例值："6890452208593372671"

请求体示例 ​

json
{
    "version_id": "6890452208593372697",
    "job_level_id": "6890452208593372679",
    "job_grade_id": "6890452208593372679",
    "employee_type_id": "6890452208593372679",
    "working_hours_type_id": "6890452208593372679",
    "work_location_id": "6890452208593372679",
    "department_id": "6890452208593372679",
    "job_id": "6890452208593372679",
    "probation_start_date": "2018-03-16",
    "probation_end_date": "2019-05-24",
    "primary_job_data": true,
    "effective_time": "2020-05-01 00:00:00",
    "expiration_time": "2020-05-02 00:00:00",
    "job_family_id": "1245678",
    "assignment_start_reason": {
        "enum_name": "job_status_change"
    },
    "probation_expected_end_date": "2006-01-02",
    "direct_manager_id": "6890452208593372679",
    "dotted_line_manager_id_list": [
        "6890452208593372681"
    ],
    "second_direct_manager_id": "6890452208593372679",
    "cost_center_rate": [
        {
            "cost_center_id": "6950635856373745165",
            "rate": 100
        }
    ],
    "work_shift": {
        "enum_name": "example"
    },
    "compensation_type": {
        "enum_name": "example"
    },
    "service_company": "6890452208593372680",
    "pathway_id": "6890452208593372671"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ job_datajob_data任职信息
    └ idstring任职信息 ID
    └ version_idstring任职记录版本 ID
    └ job_level_idstring职务级别 ID，枚举值及详细信息可通过【查询单个职级】接口查询获得
    └ job_grade_idstring职等 ID，枚举值及详细信息可通过【查询职等】接口查询获得
    └ employee_type_idstring人员类型 ID，枚举值及详细信息可通过【查询单个人员类型】接口查询获得
    └ working_hours_type_idstring工时制度 ID，枚举值及详细信息可通过【查询单个工时制度】接口查询获得
    └ work_location_idstring工作地点 ID，枚举值及详细信息可通过【查询单个地点】接口查询获得
    └ department_idstring部门 ID，详细信息可通过【批量查询部门】接口查询获得
    └ job_idstring职务 ID，枚举值及详细信息可通过【查询单个职务】接口查询获得
    └ probation_start_datestring试用期开始日期
    └ probation_end_datestring试用期结束日期（实际结束日期）
    └ primary_job_databoolean是否为主任职
    └ employment_idstring雇佣 ID，详细信息可以通过【搜索员工信息】接口查询获得 与 user_id_type 类型一致
    └ effective_timestring任职记录版本的生效时间
    └ expiration_timestring任职记录版本的失效时间
    └ job_family_idstring职务序列 ID，枚举值及详细信息可通过【查询单个序列】接口查询获得
    └ assignment_start_reasonenum业务类型（原：任职原因） - 可通过【获取字段详情】接口查询，查询参数如下： - object_api_name：job_data - custom_api_name：assignment_start_reason
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ probation_expected_end_datestring预计试用期结束日期
    └ weekly_working_hoursint周工作时长
    └ direct_manager_idstring直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
    └ dotted_line_manager_id_liststring\[\]虚线上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
    └ second_direct_manager_idstring第二直属上级的任职记录 ID，详细信息可通过【批量查询员工任职信息】接口查询获得
    └ cost_center_ratesupport_cost_center_item\[\]成本中心分摊信息
      └ cost_center_idstring支持的成本中心 ID，详细信息可通过【搜索成本中心信息】接口查询获得
      └ rateint分摊比例
    └ weekly_working_hours_v2number(float)周工作时长
    └ work_shiftenum排班类型，可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "job_data" - custom_api_name = "work_shift"
字段权限要求： corehr:job_data.work_shift:read 获取排班信息
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ compensation_typeenum薪资类型，可通过【获取字段详情】接口查询，查询参数如下： - object_api_name = "job_data" - custom_api_name = "compensation_type"
字段权限要求： corehr:job_data.compensation_type:read 获取薪资类型
      └ enum_namestring枚举值
      └ displayi18n\[\]枚举多语展示
        └ langstring语言
        └ valuestring内容
    └ service_companystring任职公司，可通过【查询单个公司】 查询详细信息
字段权限要求： corehr:job_data.service_company:read 获取任职公司
    └ pathway_idstring通道 ID
字段权限要求（满足任一）： corehr:employment.pathway:read 获取员工通道信息 corehr:employment.pathway:write 读写员工通道

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "job_data": {
            "id": "6890452208593372679",
            "version_id": "6890452208593372697",
            "job_level_id": "6890452208593372679",
            "job_grade_id": "6890452208593372679",
            "employee_type_id": "6890452208593372679",
            "working_hours_type_id": "6890452208593372679",
            "work_location_id": "6890452208593372679",
            "department_id": "6890452208593372679",
            "job_id": "6890452208593372679",
            "probation_start_date": "2018-03-16",
            "probation_end_date": "2019-05-24",
            "primary_job_data": true,
            "employment_id": "6893014062142064135",
            "effective_time": "2020-05-01 00:00:00",
            "expiration_time": "2020-05-02 00:00:00",
            "job_family_id": "1245678",
            "assignment_start_reason": {
                "enum_name": "type_1",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ]
            },
            "probation_expected_end_date": "2006-01-02",
            "weekly_working_hours": 30,
            "direct_manager_id": "6890452208593372679",
            "dotted_line_manager_id_list": [
                "6890452208593372681"
            ],
            "second_direct_manager_id": "6890452208593372679",
            "cost_center_rate": [
                {
                    "cost_center_id": "6950635856373745165",
                    "rate": 100
                }
            ],
            "weekly_working_hours_v2": 37.5,
            "work_shift": {
                "enum_name": "example",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "example"
                    }
                ]
            },
            "compensation_type": {
                "enum_name": "example",
                "display": [
                    {
                        "lang": "zh-CN",
                        "value": "example"
                    }
                ]
            },
            "service_company": "6890452208593372680",
            "pathway_id": "6890452208593372671"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160004request ID repeatrequest ID 重复，请检查传入参数
4001160019The sum of cost center apportionment ratio should be 100.成本中心分摊比率之和应为100
4001160003record is deleted by others记录被其他人删除
5001160999unknown error请联系技术支持
5001160997unknown meta rpc请联系技术支持
5001160998unknown vault rpc error请联系技术支持
5001160813duplicate entry record重复录入记录

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有