飞书开放平台 Server API 文档

主题

批量更正一次性支付记录 ​

通过传入的一次性支付记录数据，校验并更正一次性支付记录，并返回更正失败原因

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_update
HTTP MethodPOST
接口频率限制10 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用corehr:compensation.lump_sum_payment:write 写入一次性支付记录

请求头 ​

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

请求体 ​

名称类型必填描述
recordslump_sum_payment_for_update\[\]否要更正的一次性支付记录列表
数据校验规则：
- 长度范围：0 ～ 500
  └ idstring否一次性支付记录 id（通过【查询一次性支付记录】 接口进行查询）
示例值："7397033607132351532"
数据校验规则：
- 长度范围：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
  └ remarkstring否备注
示例值："该员工奖金数据不正确，予以更正"
数据校验规则：
- 长度范围：0 ～ 3000 字符
  └ reference_period_start_datestring否一次性支付记录所属期开始日期
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ reference_period_end_datestring否一次性支付记录所属期结束日期
示例值："2024-08-01"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ detailslump_sum_payment_detail_for_update\[\]是发放明细列表
数据校验规则：
- 长度范围：0 ～ 2147483647
    └ idstring否一次性支付记录明细id，若需要基于已有记录进行更正，请传入（通过【查询一次性支付记录】 接口进行查询）
示例值："7395133551102200876"
数据校验规则：
- 长度范围：0 ～ 255 字符
    └ 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-20"
数据校验规则：
- 长度范围：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 字符
  └ binding_period_decimalstring否绑定期带小数
示例值："12"
数据校验规则：
- 长度范围：0 ～ 255 字符
  └ operation_sourcestring否操作来源
示例值："apaas_spot"
数据校验规则：
- 长度范围：0 ～ 255 字符

请求体示例 ​

json
{
    "records": [
        {
            "id": "7397033607132351532",
            "total_amount": "2000.00",
            "binding_period": 2,
            "currency_id": "6863329932261459464",
            "issuance_frequency": 3,
            "remark": "该员工奖金数据不正确，予以更正",
            "reference_period_start_date": "2024-08-01",
            "reference_period_end_date": "2024-08-01",
            "details": [
                {
                    "id": "7395133551102200876",
                    "issuance_amount": "2000.00",
                    "issuance_status": "to_be_issued",
                    "issuance_way": "with_salary",
                    "issuance_time": "2024-08-20",
                    "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"
                }
            ],
            "binding_period_decimal": "12",
            "operation_source": "apaas_spot"
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
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服务端异常，请稍后重试

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

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