飞书开放平台 Server API 文档

主题

获取假期类型列表 ​

获取休假设置后台配置的假期类型列表（比如年假、事假、婚假等）。对应页面功能为设置-假勤设置-假期类型

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

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/corehr/v1/leaves/leave_types
HTTP MethodGET
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可corehr:common_data.preset_data:read 获取预置数据信息 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 获取查询结果
示例值：eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
page_sizestring是分页大小
示例值：100
statusstring否假期类型状态（不传则为全部）
可选值有：
- 1：已启用
- 2：已停用
示例值：1
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

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ leave_type_listleave_type\[\]假期类型列表
    └ leave_type_idstring假期类型ID，可用于 * 创建假期发放记录 * 批量查询员工请假记录 * 通过过期时间获取发放记录 * 修改发放记录
    └ leave_type_namei18n\[\]假期类型名称
      └ langstring名称信息的语言
      └ valuestring名称信息的内容
    └ statusint假期类型状态
可选值有：
- 1：已启用
- 2：已停用
    └ leave_subtype_listleave_subtype\[\]假期子类列表
      └ leave_type_idstring假期子类ID
      └ leave_type_namei18n\[\]假期子类名称
        └ langstring名称信息的语言
        └ valuestring名称信息的内容
    └ created_atstring假期类型的创建时间，格式为秒级时间戳
    └ created_bystring假期类型的创建人，值为创建人的员工 ID。与入参 user_id_type 类型一致
    └ updated_atstring假期类型的更新时间，格式为秒级时间戳
    └ updated_bystring假期类型的更新人，值为更新人的员工 ID。与入参 user_id_type 类型一致
  └ has_moreboolean是否还有更多项
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "leave_type_list": [
            {
                "leave_type_id": "4718803945687580505",
                "leave_type_name": [
                    {
                        "lang": "zh_CN",
                        "value": "张三"
                    }
                ],
                "status": 2,
                "leave_subtype_list": [
                    {
                        "leave_type_id": "4718803945687580505",
                        "leave_type_name": [
                            {
                                "lang": "zh_CN",
                                "value": "张三"
                            }
                        ]
                    }
                ],
                "created_at": "1658730384",
                "created_by": "7104164629974646786",
                "updated_at": "1658996995",
                "updated_by": "7112112899636854812"
            }
        ],
        "has_more": true,
        "page_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
    }
}

错误码 ​

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无权访问该员工数据

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

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