飞书开放平台 Server API 文档

主题

批量查询员工假期余额 ​

批量获取员工各个假期的余额数据。对应页面为假勤管理-休假管理-假期报表

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

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/leaves/leave_balances
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 获取查询结果
示例值：{"eu_nc":"[\"6994333322503669260\"]"}
page_sizestring是分页大小
示例值：20
as_of_datestring否查询截止日期，即截止到某天余额数据的日期（不传则默认为当天）。格式为yyyy-MM-dd
示例值：2022-07-29
employment_id_liststring\[\]否员工 ID 列表，最大 100 个（不传则默认查询全部员工），对应user_id_type。请注意：此接口为get请求，所以传入数组时需要满足get请求传入数组的规范，例如employment_id_list=6919733291281024522&employment_id_list=6919733291281024523
示例值：6919733291281024526
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
time_zonestring否查询时区
示例值：Asia/Shanghai
include_offboardboolean否是否获取离职折算字段，默认值为false
示例值：true

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ employment_leave_balance_listemployment_leave_balance\[\]员工假期余额信息列表
    └ employment_idstring雇佣信息ID，对应user_id_type
    └ employment_namei18n\[\]员工姓名
      └ langstring名称信息的语言
      └ valuestring名称信息的内容
    └ as_of_datestring截止日期，即查询截止到某天余额数据的日期。格式为yyyy-MM-dd
    └ leave_balance_listleave_balance\[\]假期余额列表
      └ leave_type_idstring假期类型ID，可用于 * 创建假期发放记录 * 批量查询员工请假记录 * 通过过期时间获取发放记录 * 修改发放记录
      └ leave_type_namei18n\[\]假期类型名称
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
      └ historical_cycles_leftstring历史结转余额
      └ this_cycle_totalstring当前周期发放
      └ this_cycle_takenstring已休（归属当前周期）
      └ leave_balancestring假期余额
      └ leave_duration_unitint假期时长单位
可选值有：
- 1: 天
- 2: 小时
      └ history_cycle_accrualstring历史结转发放，当入参include_offboard为true时返回
      └ balance_in_current_cyclestring当前周期余额
      └ takenstring已休时长，当入参include_offboard为true时返回
      └ taken_history_cyclestring历史周期已休时长
      └ offboarding_balancestring余额（离职折算），当入参include_offboard为true时返回
      └ taken_current_datestring已休时长（截止当日），当入参include_offboard为true时返回
      └ offboarding_grantedstring本周期授予时长（离职折算），当入参include_offboard为true时返回
  └ has_moreboolean是否还有更多项
  └ page_tokenstring分页标记，当 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状态码错误码描述排查建议
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未找到用户信息
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无权访问该员工数据

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

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