# 批量查询员工假期余额 批量获取员工各个假期的余额数据。对应页面为假勤管理-休假管理-[假期报表](https://example.feishu.cn/people/workforce-management/manage/leave/leave_admin/balance) **注意事项**：仅飞书人事企业版可用 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/corehr/v1/leaves/leave_balances HTTP Method | GET 接口频率限制 | [100 次/分钟](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 获取核心人事信息(corehr:corehr:readonly)
获取休假信息(corehr:leave:read)
更新核心人事信息(corehr:corehr) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly) ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 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 获取查询结果
**示例值**：`{"eu_nc":"[\"6994333322503669260\"]"}` page_size | string | 是 | 分页大小
**示例值**：20 as_of_date | string | 否 | 查询截止日期，即截止到某天余额数据的日期（不传则默认为当天）。格式为yyyy-MM-dd
**示例值**：2022-07-29 employment_id_list | string\[\] | 否 | 员工 ID 列表，最大 100 个（不传则默认查询全部员工），对应user_id_type。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如employment_id_list=6919733291281024522&employment_id_list=6919733291281024523
**示例值**：6919733291281024526 user_id_type | string | 否 | 用户 ID 类型
**示例值**：people_corehr_id
**可选值有**：
- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)
- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)
- 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)
- people_corehr_id：以飞书人事的 ID 来识别用户
**默认值**：`people_corehr_id`
**当值为 `user_id`，字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly) time_zone | string | 否 | 查询时区
**示例值**：Asia/Shanghai include_offboard | boolean | 否 | 是否获取离职折算字段，默认值为false
**示例值**：true ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- employment_leave_balance_list | employment_leave_balance\[\] | 员工假期余额信息列表 employment_id | string | 雇佣信息ID，对应user_id_type employment_name | i18n\[\] | 员工姓名 lang | string | 名称信息的语言 value | string | 名称信息的内容 as_of_date | string | 截止日期，即查询截止到某天余额数据的日期。格式为yyyy-MM-dd leave_balance_list | leave_balance\[\] | 假期余额列表 leave_type_id | string | 假期类型ID，可用于
* [创建假期发放记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/leave_granting_record/create)
* [批量查询员工请假记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/corehr-v1/leave/leave_request_history)
* [通过过期时间获取发放记录](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/leave_employ_expire_record/get)
* [修改发放记录
](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/attendance-v1/leave_accrual_record/patch) leave_type_name | i18n\[\] | 假期类型名称 lang | string | 名称信息的语言 value | string | 名称信息的内容 historical_cycles_left | string | 历史结转余额 this_cycle_total | string | 当前周期发放 this_cycle_taken | string | 已休（归属当前周期） leave_balance | string | 假期余额 leave_duration_unit | int | 假期时长单位
可选值有：
- 1: 天
- 2: 小时 history_cycle_accrual | string | 历史结转发放，当入参include_offboard为true时返回 balance_in_current_cycle | string | 当前周期余额 taken | string | 已休时长，当入参include_offboard为true时返回 taken_history_cycle | string | 历史周期已休时长 offboarding_balance | string | 余额（离职折算），当入参include_offboard为true时返回 taken_current_date | string | 已休时长（截止当日），当入参include_offboard为true时返回 offboarding_granted | string | 本周期授予时长（离职折算），当入参include_offboard为true时返回 has_more | boolean | 是否还有更多项 page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "employment_leave_balance_list": [ { "employment_id": "4718803945687580505", "employment_name": [ { "lang": "zh-CN", "value": "张三" } ], "as_of_date": "2022-07-29", "leave_balance_list": [ { "leave_type_id": "4718803945687580505", "leave_type_name": [ { "lang": "zh-CN", "value": "张三" } ], "historical_cycles_left": "0", "this_cycle_total": "0", "this_cycle_taken": "0", "leave_balance": "0", "leave_duration_unit": 1, "history_cycle_accrual": "0", "balance_in_current_cycle": "0", "taken": "0", "taken_history_cycle": "0", "offboarding_balance": "0", "taken_current_date": "0", "offboarding_granted": "0" } ] } ], "has_more": true, "page_token": "{\"eu_nc\":\"[\\\"6994333322503669260\\\"]\"}" } } ``` ### 错误码 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 | 获取员工信息失败 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 | 检查员工是否符合假期计划适用范围时发生错误 500 | 1160014 | Error occurred when calculate accrual record | 计算授予计划错误 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 | 未找到用户信息 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 | 假期余额计算出错 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 | 无权访问该员工数据