# 批量查询员工请假记录

批量获取员工的请假记录数据。对应页面为假勤管理-休假管理-[请假记录](https://example.feishu.cn/people/workforce-management/manage/leave/leave_admin/leave_request)

**注意事项**：仅飞书人事企业版可用

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/corehr/v1/leaves/leave_request_history
HTTP Method | GET
接口频率限制 | [100 次/分钟](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 获取核心人事信息(corehr:corehr:readonly)<br>获取休假信息(corehr:leave:read)<br>更新核心人事信息(corehr:corehr)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果<br>**示例值**："7356863257632491046"
page_size | string | 是 | 分页大小，最小10，最大1000<br>**示例值**：100
employment_id_list | string\[\] | 否 | 员工 ID 列表，最大 100 个（不传则默认查询全部员工），ID 类型与 user_id_type 一致。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如employment_id_list=6919733291281024522&employment_id_list=6919733291281024523<br>**示例值**：6919733291281024522
initiator_id_list | string\[\] | 否 | 休假发起人 ID 列表，最大 100 个，ID 类型与 user_id_type 一致。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如initiator_id_list=6919733291281024522&initiator_id_list=6919733291281024523<br>**示例值**：6919733291281024522
leave_request_status | string\[\] | 否 | 请假记录的状态，不填为不过滤状态。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如leave_request_status =1&leave_request_status=2<br>可选值有：<br>- 1：已通过<br>- 2：审批中<br>- 3：审批中（更正）<br>- 4：审批中（取消休假）<br>- 5：审批中（返岗）<br>- 6：已返岗<br>- 7：已拒绝<br>- 8：已取消<br>- 9：已撤回<br>**示例值**：1
leave_type_id_list | string\[\] | 否 | 假期类型 ID 列表，枚举值可通过[获取假期类型列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/leave/leave_types)接口获取。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如leave_type_id_list =4718803945687580501&leave_type_id_list=4718803945687580500<br>**示例值**：4718803945687580501
leave_start_date_min | string | 否 | 休假开始时间晚于等于的日期，格式为yyyy-MM-dd<br>**示例值**：2022-07-20
leave_start_date_max | string | 否 | 休假开始时间早于等于的日期，格式为yyyy-MM-dd<br>**示例值**：2022-07-20
leave_end_date_min | string | 否 | 休假结束时间晚于等于的日期，格式为yyyy-MM-dd<br>**示例值**：2022-07-20
leave_end_date_max | string | 否 | 休假结束时间早于等于的日期，格式为yyyy-MM-dd<br>**示例值**：2022-07-20
leave_submit_date_min | string | 否 | 休假发起时间晚于等于的日期，格式为yyyy-MM-dd<br>**示例值**：2022-07-20
leave_submit_date_max | string | 否 | 休假发起时间早于等于的日期，格式为yyyy-MM-dd<br>**示例值**：2022-07-20
user_id_type | string | 否 | 用户 ID 类型<br>**示例值**：people_corehr_id<br>**可选值有**：<br>- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br>- people_corehr_id：以飞书人事的 ID 来识别用户<br>**默认值**：`people_corehr_id`<br>**当值为 `user_id`，字段权限要求**：<br>获取用户 user ID(contact:user.employee_id:readonly)
leave_update_time_min | string | 否 | 请假记录更新时间晚于等于的时间，格式为yyyy-MM-dd HH:mm:ss<br>**示例值**：2022-10-24 10:00:00
leave_update_time_max | string | 否 | 请假记录更新时间早于等于的时间，格式为yyyy-MM-dd HH:mm:ss<br>**示例值**：2022-10-24 10:00:00
return_detail | boolean | 否 | （暂未开放）是否返回请假详情，若为true，将在每条请假记录的details字段返回请假详情<br>**示例值**：false<br>**默认值**：`false`
leave_term_type | int | 否 | 指定过滤长/短假类型，0表示不过滤，1表示仅获取短假，2表示仅获取长假, 默认0<br>**示例值**：1<br>**默认值**：`0`
time_zone | string | 否 | 请假记录所在时区<br>**示例值**：Asia/Shanghai
data_source | int | 否 | （暂未开放）请假记录数据源，1表示中国大陆休假，2表示海外休假，不传或0表示不过滤<br>**示例值**：1
db_update_time_min | string | 否 | （暂未开放）请假记录DB更新时间晚于等于的时间，格式为yyyy-MM-dd HH:mm:ss<br>**示例值**：2022-10-24 10:00:00
db_update_time_max | string | 否 | （暂未开放）请假记录DB更新时间早于等于的时间，格式为yyyy-MM-dd HH:mm:ss<br>**示例值**：2022-10-24 10:00:00
wd_need_amount_zero_records | boolean | 否 | WorkDay专用 是否返回0值的请假记录，若为true，将返回0值的请假记录<br>**示例值**：false<br>**默认值**：`false`
wd_need_denied_and_canceled_record | boolean | 否 | WorkDay专用 是否拒绝和取消的请假记录，若为true，将返回拒绝和取消的请假记录<br>**示例值**：false<br>**默认值**：`false`
wd_paid_type | int | 否 | WorkDay专用 扣薪类型, 1不参与算薪 2影响算薪 3不影响算薪<br>**示例值**：1

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
leave_request_list | leave_request\[\] | 请假记录信息列表
leave_request_id | string | 请假记录ID
employment_id | string | 员工ID，ID 类型与 user_id_type 一致
employment_name | i18n\[\] | 员工姓名
lang | string | 名称信息的语言
value | string | 名称信息的内容
leave_type_id | string | 假期类型ID
leave_type_name | i18n\[\] | 假期类型名称
lang | string | 名称信息的语言
value | string | 名称信息的内容
start_time | string | 假期开始时间，格式可能为：<br>- 字符串日期：如 "2022-09-09"<br>- 字符串日期加 morning/afternoon：如 "2022-09-09 morning""<br>- 小时假如需返回精准到小时的时间格式，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW) 开通
end_time | string | 假期结束时间，格式可能为：<br>- 字符串日期：如 "2022-09-09"<br>- 字符串日期加 morning/afternoon：如 "2022-09-09 morning""<br>- 小时假如需返回精准到小时的时间格式，请联系[技术支持](https://applink.feishu.cn/TLJpeNdW) 开通
leave_duration | string | 假期时长
leave_duration_unit | int | 假期时长单位<br>可选值有：<br>- 1: 天<br>- 2: 小时
leave_request_status | int | 请假记录的状态<br>可选值有：<br>- 1：已通过<br>- 2：审批中<br>- 3：审批中（更正）<br>- 4：审批中（取消休假）<br>- 5：审批中（返岗）<br>- 6：已返岗<br>- 7：已拒绝<br>- 8：已取消<br>- 9：已撤回
grant_source | string | 数据来源<br>可选值有：<br>- "manual"：手动创建<br>- "system"：系统创建"
return_time | string | 返岗时间，格式为秒级时间戳
submitted_at | string | 发起时间，格式为秒级时间戳
submitted_by | string | 发起人，ID 类型与 user_id_type 一致
notes | string | 备注
approval_date | string | 审批通过日期，格式为yyyy-MM-dd
is_deducted | boolean | （暂未开放）是否带薪
details | leave_request_detail\[\] | 请假详情
leave_request_id | string | 请假记录id
leave_date | string | 假期发生日期
leave_duration | string | 假期时长
leave_duration_unit | int | 假期时长单位，1：天，2：小时
paid_type | int | 是否影响算薪，1：不参与算薪计算, 非对应的日期类型或者无对应的假期计划，2：影响算薪，3：不影响算薪
leave_type_code | string | （暂未开放）假期类型枚举
actual_end_date | string | （暂未开放）实际结束日期，格式为yyyy-MM-dd
estimated_end_date | string | （暂未开放）预估结束日期，格式为yyyy-MM-dd
time_zone | string | 时区
data_source | int | （暂未开放）请假记录数据来源
leave_process_id | string\[\] | 请假申请流程ID。注意：导入的请假不会返回leave_process_id。可用于[获取单个流程详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/process/get)
leave_correct_process_id | string\[\] | 请假更正流程ID。可用于[获取单个流程详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/process/get)
leave_cancel_process_id | string\[\] | 请假取消流程ID。可用于[获取单个流程详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/process/get)
leave_return_process_id | string\[\] | 请假返岗流程ID。可用于[获取单个流程详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/process/get)
wd_paid_type | int | WorkDay专用 扣薪类型, 1不参与算薪 2影响算薪 3不影响算薪
leave_correct_process_info | leave_process_info\[\] | 请假更正流程信息
process_id | string | 流程id。注意：导入的请假不会返回leave_process_id。详情可查看[获取单个流程详情](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/corehr-v2/process/get)
process_status | string | 流程状态<br>可选值有<br>- "inProgress"：审批中<br>- "rejected"：已拒绝<br>- "withdrawn"：已撤回<br>- "passed"：已通过<br>- "revoked"：已撤销<br>- "toStart"：待发起
process_apply_time | string | 流程发起时间
workday_extend_infos | leave_extend_item\[\] | workday扩展字段信息
key | string | 扩展字段的键
value | string | 扩展字段的值
leave_tag_conf | leave_tag_conf | （暂未开放）请假标签配置
tags | tag\[\] | 请假标签列表
key | string | 标签键
values | string\[\] | 标签值列表
has_more | boolean | 是否还有更多项
page_token | string | 分页标记，当 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状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1160001 | No tenant ID | 租户ID为空
400 | 1160002 | Invalid granting unit | 授予单位参数不合法，请检查参数是否符合接口要求
400 | 1160003 | Invalid effective date | 日期格式必须是类似“2020-01-01”
400 | 1160004 | Invalid granting quantity | 必须是能解析成数字的字符串，例如“2.5”
400 | 1160005 | Accessed data object not found | 检查leaveTypeID是否正确
400 | 1160006 | Employment not found | 检查employmentID是否正确
400 | 1160007 | Leave plan version not found | 假期计划版本数据不存在，请检查该类型的假期对应的计划配置是否创建
400 | 1160008 | Error occurred while checking if the employee is eligible for the vacation plan | 员工不适用于假期计划版本，请检查该假期计划适用人员范围是否和员工信息匹配
400 | 1160009 | Accrual rule not found | 检查该假期计划版本是否正确创建，是否存在有效的发放规则
400 | 1160010 | Granting record already exists | response里会带上已存在的授予记录的信息，用户可以将其取出，不需要再重试请求
500 | 1160011 | Error occurred when getting employment information | 获取员工信息失败，请稍后重试，若仍失败请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
500 | 1160012 | An exception occurs in the database | 数据库异常，请联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
500 | 1160013 | Error occurred while checking if the employee is eligible for the scope of application of the vacation plan | 检查员工是否符合假期计划适用范围时发生错误，请稍后重试，若仍失败请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
500 | 1160014 | Error occurred when calculate accrual record | 计算授予计划错误，请稍后重试，若仍失败请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1160024 | There is a subclass for the leave type, but the subclass ID has not been passed | 如果假期类型存在子类，那么leaveTypeID必须传子类ID
400 | 1160025 | The granting quantity range is from -9999 to 9999 | 额度范围为-9999～9999
400 | 1160026 | The number of decimal places of the granted quantity cannot exceed 6 | 发放数量最多6位小数
400 | 1160027 | The length of the granting reason cannot exceed 3000 | 授予原因长度最多3000
500 | 1160028 | There is an error in the unit conversion configuration in the granting rule | 检查假期计划版本的单位转换规则是否配置正确
400 | 1160029 | The leave type has been deactivated | 不能往已停用的假期类型写发放记录
500 | 1169999 | Unknown error | 未知错误，请联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
500 | 1160015 | Internal error | 内部错误，请联系 [技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1160016 | Invalid param | 对照接口文档的入参排查，是否漏填参数、格式错误等（例如数值参数传了字母、日期格式错误等）
400 | 1160017 | User not found | 未找到用户信息，请检查传入的用户 ID 是否正确，确认用户存在
500 | 1160018 | Invalid leave balance calculate Conf | 无效的假期余额计算配置，请检查配置是否符合接口文档要求
500 | 1160019 | The calculation result of leave balance is empty | 假期余额计算为空，请检查员工假期计划配置是否正确
400 | 1160020 | When calculating the leave balance, there is no leave plan version that matches the employee | 没有与员工匹配的假期计划版本，请检查假期计划适用范围是否匹配该员工
400 | 1160021 | For the leave type that is not granted according to the cycle, balance calculation is not supported | 不按周期授予的假期类型，不支持余额计算
400 | 1160022 | The data of the leave plan version is invalid | 假期计划版本数据不合法，请检查假期计划版本的配置信息是否合法
500 | 1160023 | Error occurred when calculating the leave balance | 假期余额计算出错，请稍后重试，若仍失败请联系[技术支持](https://applink.feishu.cn/TLJpeNdW)
400 | 1160030 | The length of the granted unique ID cannot exceed 64 | 授予唯一ID长度不能超过64
400 | 1160031 | This granting record cannot be edited or deleted | 该授予记录不可编辑或删除
400 | 1160032 | The expiration time of this granting record is invalid | 该授予记录过期时间不合法
400 | 1160033 | The effective date is after the granting date | 生效日期在发放日期之后
400 | 1160034 | The expiration date format is incorrect | 失效日期格式错误
400 | 1160035 | No permission to access the employee data | 无权访问该员工数据，请确认应用已获取访问该员工数据的权限