飞书开放平台 Server API 文档

主题

创建假期发放记录 ​

向飞书人事休假系统写入假期发放记录。对应假勤管理-休假管理-发放记录的创建或者导入功能

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

请求 ​

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

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_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来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
leave_type_idstring是假期类型 ID，枚举值可通过获取假期类型列表接口获取（若假期类型下存在假期子类，此处仅支持传入假期子类的 ID）
示例值："7111688079785723436"
employment_idstring是员工 ID，飞书人事的雇员id。对应user_id_type
示例值："6982509313466189342"
granting_quantitystring是发放数量（小数位数不能超过6位，授予数量范围为-9999~9999）
示例值："0.5"
granting_unitint是发放时长单位
可选值有：
- 1: 天 - 2: 小时
示例值：1
effective_datestring是生效时间，格式为yyyy-MM-dd
示例值："2022-01-01"
expiration_datestring否失效时间，格式为yyyy-MM-dd
示例值："2022-01-01"
section_typeint否是否参与折算（1不参与折算，2参与折算）。默认不折算
示例值：1
reasoni18n\[\]是发放原因
  └ langstring是名称信息的语言
示例值："zh_CN"
  └ valuestring是名称信息的内容
示例值："张三"
external_idstring否自定义外部 ID，可用于避免数据重复写入（不能超过 64 字符）。如果重复录入，不会创建新纪录、也不会更新原始记录
示例值："111"

请求体示例 ​

json
{
    "leave_type_id": "7111688079785723436",
    "employment_id": "6982509313466189342",
    "granting_quantity": "0.5",
    "granting_unit": 1,
    "effective_date": "2022-01-01",
    "expiration_date": "2022-01-01",
    "section_type": 1,
    "reason": [
        {
            "lang": "zh_CN",
            "value": "张三"
        }
    ],
    "external_id": "111"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ leave_granting_recordleave_granting_record假期发放记录
    └ idstring假期发放记录 ID，可用与删除假期发放记录和修改发放记录
    └ employment_idstring员工 ID，对应user_id_type
    └ leave_type_idstring假期类型 ID
    └ granting_quantitystring发放数量
    └ granting_unitint发放时长单位
可选值有： - 1: 天 - 2: 小时
    └ effective_datestring生效时间，格式为yyyy-MM-dd
    └ expiration_datestring失效时间（根据休假规则自动计算），格式为yyyy-MM-dd
    └ granted_byint发放来源
可选值有： - 1: 系统发放 - 2: 手动发放 - 3: 外部系统发放
    └ reasoni18n\[\]发放原因
      └ langstring名称信息的语言
      └ valuestring名称信息的内容
    └ created_atstring发放记录的创建时间，格式为毫秒级时间戳
    └ created_bystring发放记录的创建人，值为创建人的员工 ID，对应user_id_type
    └ updated_atstring发放记录的更新时间，格式为毫秒级时间戳
    └ updated_bystring发放记录的更新人，值为更新人的员工 ID，对应user_id_type
    └ section_typeint是否参与折算（1不参与折算，2参与折算）

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "leave_granting_record": {
            "id": "6893014062142064135",
            "employment_id": "6893014062142064135",
            "leave_type_id": "6893014062142064135",
            "granting_quantity": "0.5",
            "granting_unit": 1,
            "effective_date": "2022-01-01",
            "expiration_date": "2022-01-01",
            "granted_by": 3,
            "reason": [
                {
                    "lang": "zh_CN",
                    "value": "张三"
                }
            ],
            "created_at": "1608725989000",
            "created_by": "646465654545",
            "updated_at": "1608725989000",
            "updated_by": "646465654545",
            "section_type": 1
        }
    }
}

错误码 ​

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 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不能往已停用的假期类型写发放记录
4001160030The length of the granted unique ID cannot exceed 64授予唯一ID长度不能超过64
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假期余额计算出错
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无权访问该员工数据

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

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