飞书开放平台 Server API 文档

主题

批量查询员工请假记录 ​

批量获取员工的请假记录数据。对应页面为假勤管理-休假管理-请假记录

Tip: 仅飞书人事企业版可用

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/leaves/leave_request_history
HTTP MethodGET
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:corehr:readonly 获取核心人事信息 corehr:leave:read 获取休假信息 corehr:corehr 更新核心人事信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

查询参数 ​

名称类型必填描述
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值："7356863257632491046"
page_sizestring是分页大小，最小10，最大1000
示例值：100
employment_id_liststring\[\]否员工 ID 列表，最大 100 个（不传则默认查询全部员工），ID 类型与 user_id_type 一致。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如employment_id_list=6919733291281024522&employment_id_list=6919733291281024523
示例值：6919733291281024522
initiator_id_liststring\[\]否休假发起人 ID 列表，最大 100 个，ID 类型与 user_id_type 一致。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如initiator_id_list=6919733291281024522&initiator_id_list=6919733291281024523
示例值：6919733291281024522
leave_request_statusstring\[\]否请假记录的状态，不填为不过滤状态。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如leave_request_status =1&leave_request_status=2
可选值有：
- 1：已通过
- 2：审批中
- 3：审批中（更正）
- 4：审批中（取消休假）
- 5：审批中（返岗）
- 6：已返岗
- 7：已拒绝
- 8：已取消
- 9：已撤回
示例值：1
leave_type_id_liststring\[\]否假期类型 ID 列表，枚举值可通过获取假期类型列表接口获取。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如leave_type_id_list =4718803945687580501&leave_type_id_list=4718803945687580500
示例值：4718803945687580501
leave_start_date_minstring否休假开始时间晚于等于的日期，格式为yyyy-MM-dd
示例值：2022-07-20
leave_start_date_maxstring否休假开始时间早于等于的日期，格式为yyyy-MM-dd
示例值：2022-07-20
leave_end_date_minstring否休假结束时间晚于等于的日期，格式为yyyy-MM-dd
示例值：2022-07-20
leave_end_date_maxstring否休假结束时间早于等于的日期，格式为yyyy-MM-dd
示例值：2022-07-20
leave_submit_date_minstring否休假发起时间晚于等于的日期，格式为yyyy-MM-dd
示例值：2022-07-20
leave_submit_date_maxstring否休假发起时间早于等于的日期，格式为yyyy-MM-dd
示例值：2022-07-20
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
leave_update_time_minstring否请假记录更新时间晚于等于的时间，格式为yyyy-MM-dd HH:mm:ss
示例值：2022-10-24 10:00:00
leave_update_time_maxstring否请假记录更新时间早于等于的时间，格式为yyyy-MM-dd HH:mm:ss
示例值：2022-10-24 10:00:00
return_detailboolean否（暂未开放）是否返回请假详情，若为true，将在每条请假记录的details字段返回请假详情
示例值：false
默认值：false
leave_term_typeint否指定过滤长/短假类型，0表示不过滤，1表示仅获取短假，2表示仅获取长假, 默认0
示例值：1
默认值：0
time_zonestring否请假记录所在时区
示例值：Asia/Shanghai
data_sourceint否（暂未开放）请假记录数据源，1表示中国大陆休假，2表示海外休假，不传或0表示不过滤
示例值：1
db_update_time_minstring否（暂未开放）请假记录DB更新时间晚于等于的时间，格式为yyyy-MM-dd HH:mm:ss
示例值：2022-10-24 10:00:00
db_update_time_maxstring否（暂未开放）请假记录DB更新时间早于等于的时间，格式为yyyy-MM-dd HH:mm:ss
示例值：2022-10-24 10:00:00
wd_need_amount_zero_recordsboolean否WorkDay专用 是否返回0值的请假记录，若为true，将返回0值的请假记录
示例值：false
默认值：false
wd_need_denied_and_canceled_recordboolean否WorkDay专用 是否拒绝和取消的请假记录，若为true，将返回拒绝和取消的请假记录
示例值：false
默认值：false
wd_paid_typeint否WorkDay专用 扣薪类型, 1不参与算薪 2影响算薪 3不影响算薪
示例值：1

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ leave_request_listleave_request\[\]请假记录信息列表
    └ leave_request_idstring请假记录ID
    └ employment_idstring员工ID，ID 类型与 user_id_type 一致
    └ employment_namei18n\[\]员工姓名
      └ langstring名称信息的语言
      └ valuestring名称信息的内容
    └ leave_type_idstring假期类型ID
    └ leave_type_namei18n\[\]假期类型名称
      └ langstring名称信息的语言
      └ valuestring名称信息的内容
    └ start_timestring假期开始时间，格式可能为：
- 字符串日期：如 "2022-09-09"
- 字符串日期加 morning/afternoon：如 "2022-09-09 morning"" - 小时假如需返回精准到小时的时间格式，请联系技术支持 开通
    └ end_timestring假期结束时间，格式可能为：
- 字符串日期：如 "2022-09-09"
- 字符串日期加 morning/afternoon：如 "2022-09-09 morning"" - 小时假如需返回精准到小时的时间格式，请联系技术支持 开通
    └ leave_durationstring假期时长
    └ leave_duration_unitint假期时长单位
可选值有：
- 1: 天
- 2: 小时
    └ leave_request_statusint请假记录的状态
可选值有：
- 1：已通过
- 2：审批中
- 3：审批中（更正） - 4：审批中（取消休假） - 5：审批中（返岗） - 6：已返岗 - 7：已拒绝 - 8：已取消 - 9：已撤回
    └ grant_sourcestring数据来源
可选值有：
- "manual"：手动创建
- "system"：系统创建"
    └ return_timestring返岗时间，格式为秒级时间戳
    └ submitted_atstring发起时间，格式为秒级时间戳
    └ submitted_bystring发起人，ID 类型与 user_id_type 一致
    └ notesstring备注
    └ approval_datestring（暂未开放）审批通过日期，格式为yyyy-MM-dd
    └ is_deductedboolean（暂未开放）是否带薪
    └ detailsleave_request_detail\[\]请假详情
      └ leave_request_idstring请假记录id
      └ leave_datestring假期发生日期
      └ leave_durationstring假期时长
      └ leave_duration_unitint假期时长单位，1：天，2：小时
      └ paid_typeint是否影响算薪，1：不参与算薪计算, 非对应的日期类型或者无对应的假期计划，2：影响算薪，3：不影响算薪
    └ leave_type_codestring（暂未开放）假期类型枚举
    └ actual_end_datestring（暂未开放）实际结束日期，格式为yyyy-MM-dd
    └ estimated_end_datestring（暂未开放）预估结束日期，格式为yyyy-MM-dd
    └ time_zonestring时区
    └ data_sourceint（暂未开放）请假记录数据来源
    └ leave_process_idstring\[\]请假申请流程ID。注意：导入的请假不会返回leave_process_id。可用于获取单个流程详情
    └ leave_correct_process_idstring\[\]请假更正流程ID。可用于获取单个流程详情
    └ leave_cancel_process_idstring\[\]请假取消流程ID。可用于获取单个流程详情
    └ leave_return_process_idstring\[\]请假返岗流程ID。可用于获取单个流程详情
    └ wd_paid_typeintWorkDay专用 扣薪类型, 1不参与算薪 2影响算薪 3不影响算薪
    └ leave_correct_process_infoleave_process_info\[\]请假更正流程信息
      └ process_idstring流程id。注意：导入的请假不会返回leave_process_id。详情可查看获取单个流程详情
      └ process_statusstring流程状态 可选值有 - "inProgress"：审批中
- "rejected"：已拒绝
- "withdrawn"：已撤回
- "passed"：已通过
- "revoked"：已撤销
- "toStart"：待发起
      └ process_apply_timestring流程发起时间
    └ workday_extend_infosleave_extend_item\[\]workday扩展字段信息
      └ keystring扩展字段的键
      └ valuestring扩展字段的值
    └ leave_tag_confleave_tag_conf（暂未开放）请假标签配置
      └ tagstag\[\]请假标签列表
        └ keystring标签键
        └ valuesstring\[\]标签值列表
  └ has_moreboolean是否还有更多项
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "leave_request_list": [
            {
                "leave_request_id": "4718803945687580505",
                "employment_id": "4718803945687580505",
                "employment_name": [
                    {
                        "lang": "zh-CN",
                        "value": "张三"
                    }
                ],
                "leave_type_id": "0",
                "leave_type_name": [
                    {
                        "lang": "zh-CN",
                        "value": "年假"
                    }
                ],
                "start_time": "2022-07-06",
                "end_time": "2023-01-05",
                "leave_duration": "2",
                "leave_duration_unit": 2,
                "leave_request_status": 2,
                "grant_source": "manual",
                "return_time": "1662134400",
                "submitted_at": "1659080476",
                "submitted_by": "7109664941775241244",
                "notes": "备注",
                "approval_date": "2022-09-09",
                "is_deducted": false,
                "details": [
                    {
                        "leave_request_id": "4718803945687580505",
                        "leave_date": "2022-07-07",
                        "leave_duration": "1",
                        "leave_duration_unit": 1,
                        "paid_type": 1
                    }
                ],
                "leave_type_code": "Annual Leave",
                "actual_end_date": "2022-08-02",
                "estimated_end_date": "2022-08-02",
                "time_zone": "Asia/Shanghai",
                "data_source": 1,
                "leave_process_id": [
                    "7304865941202929196"
                ],
                "leave_correct_process_id": [
                    "7304865941202929196"
                ],
                "leave_cancel_process_id": [
                    "7304865941202929196"
                ],
                "leave_return_process_id": [
                    "7304865941202929196"
                ],
                "wd_paid_type": 1,
                "leave_correct_process_info": [
                    {
                        "process_id": "4718803945687580505",
                        "process_status": "passed",
                        "process_apply_time": "2024-01-01 00:00:00"
                    }
                ],
                "workday_extend_infos": [
                    {
                        "key": "SampleKey",
                        "value": "SampleValue"
                    }
                ],
                "leave_tag_conf": {
                    "tags": [
                        {
                            "key": "leave_category",
                            "values": [
                                "Life events"
                            ]
                        }
                    ]
                }
            }
        ],
        "has_more": true,
        "page_token": "[1712932008000,\"7356863257632491046\"]"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001160001No tenant ID租户ID为空
4001160002Invalid granting unit授予单位参数不合法，请检查参数是否符合接口要求
4001160003Invalid effective date日期格式必须是类似“2020-01-01”
4001160004Invalid granting quantity必须是能解析成数字的字符串，例如“2.5”
4001160005Accessed data object not found检查leaveTypeID是否正确
4001160006Employment not found检查employmentID是否正确
4001160007Leave plan version not found假期计划版本数据不存在，请检查该类型的假期对应的计划配置是否创建
4001160008Error occurred while checking if the employee is eligible for the vacation plan员工不适用于假期计划版本，请检查该假期计划适用人员范围是否和员工信息匹配
4001160009Accrual rule not found检查该假期计划版本是否正确创建，是否存在有效的发放规则
4001160010Granting record already existsresponse里会带上已存在的授予记录的信息，用户可以将其取出，不需要再重试请求
5001160011Error occurred when getting employment information获取员工信息失败，请稍后重试，若仍失败请联系技术支持
5001160012An exception occurs in the database数据库异常，请联系 技术支持
5001160013Error occurred while checking if the employee is eligible for the scope of application of the vacation plan检查员工是否符合假期计划适用范围时发生错误，请稍后重试，若仍失败请联系技术支持
5001160014Error occurred when calculate accrual record计算授予计划错误，请稍后重试，若仍失败请联系技术支持
4001160024There is a subclass for the leave type, but the subclass ID has not been passed如果假期类型存在子类，那么leaveTypeID必须传子类ID
4001160025The granting quantity range is from -9999 to 9999额度范围为-9999～9999
4001160026The number of decimal places of the granted quantity cannot exceed 6发放数量最多6位小数
4001160027The length of the granting reason cannot exceed 3000授予原因长度最多3000
5001160028There is an error in the unit conversion configuration in the granting rule检查假期计划版本的单位转换规则是否配置正确
4001160029The leave type has been deactivated不能往已停用的假期类型写发放记录
5001169999Unknown error未知错误，请联系 技术支持
5001160015Internal error内部错误，请联系 技术支持
4001160016Invalid param对照接口文档的入参排查，是否漏填参数、格式错误等（例如数值参数传了字母、日期格式错误等）
4001160017User not found未找到用户信息，请检查传入的用户 ID 是否正确，确认用户存在
5001160018Invalid leave balance calculate Conf无效的假期余额计算配置，请检查配置是否符合接口文档要求
5001160019The calculation result of leave balance is empty假期余额计算为空，请检查员工假期计划配置是否正确
4001160020When calculating the leave balance, there is no leave plan version that matches the employee没有与员工匹配的假期计划版本，请检查假期计划适用范围是否匹配该员工
4001160021For the leave type that is not granted according to the cycle, balance calculation is not supported不按周期授予的假期类型，不支持余额计算
4001160022The data of the leave plan version is invalid假期计划版本数据不合法，请检查假期计划版本的配置信息是否合法
5001160023Error occurred when calculating the leave balance假期余额计算出错，请稍后重试，若仍失败请联系技术支持
4001160030The length of the granted unique ID cannot exceed 64授予唯一ID长度不能超过64
4001160031This granting record cannot be edited or deleted该授予记录不可编辑或删除
4001160032The expiration time of this granting record is invalid该授予记录过期时间不合法
4001160033The effective date is after the granting date生效日期在发放日期之后
4001160034The expiration date format is incorrect失效日期格式错误
4001160035No permission to access the employee data无权访问该员工数据，请确认应用已获取访问该员工数据的权限

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

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