飞书开放平台 Server API 文档

主题

批量创建一次性支付记录 ​

通过传入的一次性支付记录数据，校验并创建一次性支付记录，并返回创建失败原因或创建成功数据的ID

Tip: 本接口支持部分成功，失败部分详细报错信息参考 data.operate_results.code。

  • 当 data.operate_results.code 存在非 0 时，响应体 code 仍可能返回 0
  • 仅当出现非预期异常时，响应体 code 才会为非 0

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/compensation/v1/lump_sum_payment/batch_create
HTTP MethodPOST
接口频率限制10 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:compensation.lump_sum_payment:write 写入一次性支付记录
字段权限要求> 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: 以people_corehr_id来识别用户
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
recordslump_sum_payment_for_create\[\]否要创建的一次性支付信息
数据校验规则：
- 长度范围：0 ～ 500
  └ unique_idstring是外部幂等id，由上游业务决定
示例值："7402510801304718380_7309316347007764012_7402523725868058156_1726070400000_10000"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ user_idstring是员工id，具体类型由入参中的 user_id_type 指定
示例值："7337149697626801708"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ total_amountstring是总金额，字符串表达的数字，单位为入参中 currency_id 给定的币种
示例值："2000.00"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ binding_periodint是绑定期，单位为月
示例值：2
数据校验规则：
- 取值范围：0 ～ 2147483647
  └ currency_idstring是币种 id（通过【查询币种】) 接口进行查询）
示例值："6863329932261459464"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ issuance_frequencyint是发放次数，必须与 details 的长度一致
示例值：3
数据校验规则：
- 取值范围：0 ～ 2147483647
  └ item_idstring是薪酬项 id（通过【查询薪酬项】) 接口进行查询）
示例值："7411039006180312620"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ reference_period_start_datestring否一次性支付记录所属期开始日期
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ reference_period_end_datestring否一次性支付记录所属期结束日期
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ detailslump_sum_payment_detail_for_create\[\]是发放明细列表
数据校验规则：
- 长度范围：0 ～ 2147483647
    └ issuance_amountstring是一次性支付明细发放金额，可转数字的字符串，单位为入参中 currency_id 给定的币种
示例值："2000.00"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ issuance_statusstring是发放状态
示例值："to_be_issued"
可选值有：
- to_be_issued: 应发放 - not_issued: 不发放
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ issuance_waystring是发放方式
示例值："with_salary"
可选值有：
- with_salary: 随工资发放 - with_cash: 现金发放 - with_year_end_bonus: 随年终奖发放
    └ issuance_timestring是发放时间
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ belong_timestring是申请发放日期
示例值："2025-01-20"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ issuance_country_region_idstring否发放国家ID（可通过查询国家/地区信息进行查询）
示例值："6862995757234914824"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ issuance_pay_group_idstring否发放薪资组ID（可通过获取薪资组基本信息 进行查询）
示例值："6862995757234914824"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ detail_reference_period_start_datestring否一次性支付明细所属期开始日期
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ detail_reference_period_end_datestring否一次性支付明细所属期结束日期
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ remarkstring否备注
示例值："该员工表现优异，为其发放一笔奖金"
数据校验规则：
- 长度范围：0 ～ 3000 字符
  └ binding_period_decimalstring否绑定期带小数
示例值："12.56"
数据校验规则：
- 长度范围：0 ～ 255 字符

请求体示例 ​

json
{
    "records": [
        {
            "unique_id": "7402510801304718380_7309316347007764012_7402523725868058156_1726070400000_10000",
            "user_id": "7337149697626801708",
            "total_amount": "2000.00",
            "binding_period": 2,
            "currency_id": "6863329932261459464",
            "issuance_frequency": 3,
            "item_id": "7411039006180312620",
            "reference_period_start_date": "2024-08-01",
            "reference_period_end_date": "2024-08-01",
            "details": [
                {
                    "issuance_amount": "2000.00",
                    "issuance_status": "to_be_issued",
                    "issuance_way": "with_salary",
                    "issuance_time": "2024-08-01",
                    "belong_time": "2025-01-20",
                    "issuance_country_region_id": "6862995757234914824",
                    "issuance_pay_group_id": "6862995757234914824",
                    "detail_reference_period_start_date": "2024-08-01",
                    "detail_reference_period_end_date": "2024-08-01"
                }
            ],
            "remark": "该员工表现优异，为其发放一笔奖金",
            "binding_period_decimal": "12.56"
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ operate_resultslump_sum_payment_operate_result\[\]每条记录的操作结果。对于创建成功的记录，会返回创建后的一次性支付记录id
    └ idstring操作的记录的 id
    └ unique_idstring操作的记录的 unique_id
    └ codeint操作结果状态码
可选值有：
- 0: "Success" 操作成功 - 21270201: "The bonus to be changed does not exist" 要更改的奖金不存在 - 21270202: "Idempotent ID conflict" 幂等id冲突 - 21270203: "The total amount format is incorrect" 总金额格式不正确 - 21270205: "Only use the number of decimal places specified in the bonus item rules" 仅限使用奖金项规则中规定的小数位数 - 21270206: "The sum of the bonus details does not equal the total amount" 奖金明细金额之和不等于总金额 - 21270207: "issuance frequency not equal to size of details" 奖金明细总数不等于发放次数 - 21270208: "The number of issuances is less than or equal to 0" 发放次数小于等于0 - 21270209: "The currency is empty or does not exist" 币种为空或不存在 - 21270210: "Notes are too long" 备注超长 - 21270211: "The bonus details amount format is incorrect" 奖金明细金额格式不正确 - 21270213: "The bonus details payment time format is incorrect" 奖金明细的发放时间格式不正确 - 21270214: "The bonus details are issued in an illegal manner" 奖金明细的发放方式不合法 - 21270215: "The bonus details are not in a valid payment status" 奖金明细的发放状态不合法 - 21270217: "Employees are not covered by the bonus rules" 员工不在奖金项规则适用范围之内 - 21270218: "The method of awarding bonus details is not covered by the bonus item rules" 奖金明细的发放方式不在奖金项规则适用范围之内 - 21270219: "Bonus item rules do not support configuration of binding period" 奖金项规则不支持配置绑定期 - 21270220: "The bonus details payment status is "paid", and cannot be modified" 奖金明细发放状态为「已发放」，不支持修改 - 21270221: "The bonus item rules already include the currency, and other currencies cannot be specified" 奖金项规则已包含币种，不支持指定其他币种 - 21270222: "The salary item does not exist" 薪酬项不存在 - 21270223: "Employee does not exist" 员工不存在 - 21270224: "The bonus details payment status is "paid", and deletion is not supported" 奖金明细发放状态为「已发放」，不支持删除 - 21270225: "Bonus rules do not allow multiple awards" 奖金项规则不允许多次发放 - 21270226: "No data permission" 无数据权限 - 21270227: "Only positive integers are allowed for the binding period" 绑定期只允许正整数 - 21270228: "This bonus does not currently support custom binding periods. Please configure and write according to the rules for the binding period of the salary item" 该奖金暂不支持自定义绑定期，请按照薪酬项绑定期规则配置写入 - 21270229: "The application issuance date must not be later than the issuance date" 申请发放日期不得晚于发放日期 - 21270230: "The application payment date format of the bonus details is incorrect" 奖金明细的申请发放日期格式不正确 - 21270070: "The binding period and the ownership period start and end dates do not match" 绑定期和所属期开始结束日期不匹配 - 21270239: "One time payment detail reference period start date and One time payment detail reference period end date shall be filled in or left blank at the same time. Please confirm" 「一次性支付明细所属期开始日期」、「一次性支付明细所属期结束日期」需同时填写或同时为空，请确认 - 21270240: "One time payment detail reference period start date must be earlier than or equal to One time payment detail reference period end date. Please confirm" 「一次性支付明细所属期开始日期」需早于等于「一次性支付明细结束日期」，请确认 - 21270241: "One time payment detail reference period must fall within the scope of One time payment record reference period. Please adjust" 「一次性支付明细所属期」需包含在「一次性支付记录所属期」范围内，请调整
    └ messagestring操作结果描述

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "operate_results": [
            {
                "id": "7390583861280556588",
                "unique_id": "7390583861280556588",
                "code": 21270202,
                "message": "uqniue id conflict"
            }
        ]
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4002290001param is invalid参数异常，请检查入参
5002290002server error服务端异常，请稍后重试

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

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