飞书开放平台 Server API 文档

主题

操作员工离职 ​

该接口用于发起飞书人事的离职信息，支持填写离职日期、离职原因、屏蔽名单和自定义字段（附件字段除外）等。当接口成功提交后，会产生对应的离职信息变更事件。

Tip: 注意，与操作员工离职相比：

1、该接口会限制应用拥有的「员工数据」的权限范围发起离职信息，请先在「开发者后台 - 权限管理 - 数据权限-飞书人事（企业版）数据权限」中申请「员工资源」权限范围。

2、该接口还支持发起离职审批流程。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v2/offboardings/submit_v2
HTTP MethodPOST
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:offboarding.submit:write 读写员工离职信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

查询参数 ​

名称类型必填描述
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

请求体 ​

名称类型必填描述
offboarding_modeint是离职方式
示例值：1
可选值有：
- 1: 直接离职 - 2: 发起离职审批
employment_idstring是离职员工 ID（employment_id）不允许为空。ID类型与查询参数 user_id_type取值一致：
1、当user_id_type取值为open_id时，ID获取方式参考如何获取自己的Open ID。
2、当user_id_type取值为user_id时，ID获取方式参考如何获取自己的 User ID。
3、当user_id_type取值为union_id时，ID获取方式参考如何获取自己的 Union ID。
4、当user_id_type取值为people_corehr_id时，先参考如何获取自己的 User ID获取User ID。然后通过ID 转换获取雇佣ID。
示例值："6982509313466189342"
offboarding_datestring是离职日期，不允许为空，填写时需要符合YYYY-MM-DD的日期格式。
注意：按员工离职当天的工作地点时区24点生效。假设员工离职日期为2024-12-01，如果员工在中国大陆，则生效时间为东八区的2024-12-01 23:59:59。如果员工在华盛顿，则生效时间为东八区的2024-12-02 12:59:59，对应西五区的2024-12-01 23:59:59。
示例值："2022-05-18"
offboarding_reason_unique_identifierstring是离职原因，不允许为空，可通过接口 查询员工离职原因列表获取。
示例值："reason_for_offboarding_option8"
offboarding_reason_explanationstring否离职原因说明，选填，最大长度6000。
示例值："离职原因说明"
initiator_idstring否发起人 ID。这个发起人需要有飞书账号，能够登录系统。ID类型与查询参数 user_id_type取值一致：
1、当user_id_type取值为open_id时，ID获取方式参考如何获取自己的Open ID。
2、当user_id_type取值为user_id时，ID获取方式参考如何获取自己的 User ID。
3、当user_id_type取值为union_id时，ID获取方式参考如何获取自己的 Union ID。
4、当user_id_type取值为people_corehr_id时，先参考如何获取自己的 User ID获取User ID。然后通过ID 转换获取雇佣ID。
注意：
1.只有发起人可以撤销流程
2.为空时，默认系统发起人
示例值："6982509313466189341"
add_block_listboolean否是否加入离职屏蔽名单
注意：
1.取值为true时，屏蔽原因（block_reason）为必填。
2.取值为false时，不允许填写屏蔽原因（block_reason）和屏蔽原因说明（block_reason_explanation）。
3.取值为空时，不允许填写屏蔽原因（block_reason）和屏蔽原因说明（block_reason_explanation）。
4.操作离职时如果选择加入屏蔽名单，只有当员工离职生效后才会进入到屏蔽名单。
示例值：false
block_reasonstring否屏蔽原因
注意：
1.该字段取值于 人员档案配置 > 信息配置 > 离职信息 的屏蔽原因字段选项集。
2.枚举字段值也可通过获取字段详情获取，参考接口返回的 字段详情 > 字段类型配置信息 > 选项配置信息 > 选项信息 > 枚举常量集 API name
3.该字段是否必填取决于是否加入离职屏蔽名单(add_block_list)
示例值："红线"
block_reason_explanationstring否屏蔽原因说明，选填，最大长度6000。
示例值："xx 年 xx 月 xx 日因 xx 原因红线"
custom_fieldsobject_field_data\[\]否离职自定义字段。
注意：可填写的字段范围参考人员档案配置 > 信息配置 > 离职信息 中的自定义字段
数据校验规则：
- 长度范围：0 ～ 10000
  └ field_namestring是字段唯一标识
注意：
1.该字段取值于人员档案配置 > 信息配置 > 离职信息 中各字段的字段编码
2.该字段也可以通过获取自定义字段列表获取
示例值："custom_field_1__c"
  └ valuestring是自定义字段值，根据元数据定义不同，字段格式不同(如123, 123.23, "true", ["id1","id2"], "2006-01-02 15:04:05")。
注意：
1.枚举字段的枚举值取值于人员档案配置 > 信息配置 > 离职信息 对应字段选项集的选项编码。
2.枚举字段值也可通过获取字段详情获取，参考接口返回的 字段详情 > 字段类型配置信息 > 选项配置信息 > 选项信息 > 枚举常量集 API name
3.人员字段目前只支持传入员工的雇佣ID。员工的人事雇佣ID需要先获取User ID后，通过ID 转换获取
4.暂不支持填写附件类型字段。
示例值："Sandy"
retain_accountboolean否离职是否保留飞书账号
示例值：false

请求体示例 ​

json
{
    "offboarding_mode": 1,
    "employment_id": "6982509313466189342",
    "offboarding_date": "2022-05-18",
    "offboarding_reason_unique_identifier": "reason_for_offboarding_option8",
    "offboarding_reason_explanation": "离职原因说明",
    "initiator_id": "6982509313466189341",
    "add_block_list": false,
    "block_reason": "红线",
    "block_reason_explanation": "xx 年 xx 月 xx 日因 xx 原因红线",
    "custom_fields": [
        {
            "field_name": "custom_field_1__c",
            "value": "Sandy"
        }
    ],
    "retain_account": false
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ offboarding_idstring离职记录 id
  └ employment_idstring雇员 id
  └ offboarding_reason_unique_identifierstring离职原因
  └ offboarding_datestring离职日期
  └ offboarding_reason_explanationstring离职原因说明
  └ add_block_listboolean是否加入离职屏蔽名单
  └ block_reasonstring屏蔽原因
  └ block_reason_explanationstring屏蔽原因说明
  └ created_timestring创建时间
  └ retain_accountboolean离职是否保留飞书账号

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "offboarding_id": "7095671727698478604",
        "employment_id": "6982509313466189342",
        "offboarding_reason_unique_identifier": "reason_for_offboarding_option8",
        "offboarding_date": "2022-05-18",
        "offboarding_reason_explanation": "离职原因说明",
        "add_block_list": false,
        "block_reason": "红线",
        "block_reason_explanation": "xx 年 xx 月 xx 日因 xx 原因红线",
        "created_time": "2022-05-09 17:50:17",
        "retain_account": false
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5001160103general internal server error code系统内部错误，请联系管理员
5001160201has approving offboarding存在「审批中」或「待生效」的离职申请，请先撤销后再申请
5001160203no current contract所选离职日期无生效中的合同，请确认合同信息后重新提交
5001160204has future contract存在晚于离职日期生效的合同，请确认修正合同信息或离职日期后重新提交
5001160205contract has actual end date离职日期时的合同已存在实际结束日期，请确认合同信息后重新提交
5001160210has offboarding record存在「审批中」或「待生效」的离职申请，请先撤销后再申请
5001160602offboarding is earlier than probation存在晚于离职日期的转正记录，请重新选择离职日期或先撤销试用期转正申请
5001160603offboarding is earlier than transform存在晚于离职日期的异动记录，请重新选择离职日期或先撤销异动申请
4001160604reason explanation length exceed maximum离职原因说明长度超过最大限制(6000)
5001160616no valid job data该员工没有合法的任职记录，请确认任职记录后重新提交
5001161000unknown error调用上下游系统错误
4001160710invalid block list请检查屏蔽名单相关字段，并按文档提示修正后重新提交
2001161002you need to apply permission应用无权限发起该员工离职，请检查并配置权限后重新提交
5001160200has approving transform存在晚于离职日期生效的异动记录，请修正异动记录或离职日期后重新提交
5001160601offboarding is earlier than onboarding离职日期早于入职日期，请修正离职日期后重新提交
5001160617hyperlink field format is illegal超链接格式不合法，请修正超链接自定义字段的值后重新提交
5001160618text field exceeds maximum limit文本长度超长，请修正文本自定义字段的值后重新提交
5001160619enum value of the enum field is invalid选项不存在，请修正枚举自定义字段的值后重新提交
5001160621offboarding reason is required离职原因必填，请填写后重新提交
5001160622offboarding date is required离职日期必填，请填写后重新提交
5001160630invalid number value in custom fields数字自定义字段值不合法，或者小数位数超过元数据定义，请检查修改后重新提交
5001160631employee is not exist or has offboarded离职人员id不存在或已离职，请检查并修正后重新提交
5001160636employee is not exist or has offboarded离职人员或者自定义人员字段填写的id不存在，请检查并修正后重新提交
5001160637not support attachment field不支持填写附件自定义字段，请删除附件自定义字段后重新提交
5001160638invalid date value in custom fields日期自定义字段不符合YYYY-MM-DD格式，请修改后重新提交
5001160639invalid bool value in custom fields布尔自定义字段不是是否类型的值，请修改后重新提交
5001160700offboarding process not exist离职申请流程不存在，请联系飞书人事管理员进行配置后重新提交
5001160701offboarding process is disable离职申请流程未启用，请联系飞书人事管理员进行配置后重新提交
5001160702offboarding process has not active version离职申请流程没有启用的版本，请联系飞书人事管理员进行配置后重新提交

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

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