信用分账更新

此接口用于更新已发行 Boleto 的信用分账（分账支付）规则。新规则将完全替换原有规则，并适用于该 Boleto 的下一次结算。

注意！

Boleto 必须处于 registered 状态且尚未支付。
beneficiary_settlement_percentage 与 split_payment_rules 中各项百分比之和必须正好等于 100。
请求体将完全替换现有的所有分账规则（非增量更新）。
分账适用于 Boleto 的所有结算流程（SILOC、STR、公证处和 Pix QR Code），包括已生成 QR Code 的 Boleto——此时 QR Code 中的规则也会自动同步更新。
分账规则中的账户必须为开通状态并已在 QI Tech 注册（QI Tech 将根据所提供的 document_number、account_number 和 account_digit 进行查询）。

Request

ENDPOINT

/v2/bank_slip/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip/BANK_SLIP_KEY/split_payment

方法

PUT

路径参数

字段	类型	描述	字符数
`account_key`	uuidv4	Boleto 所在账户的唯一标识密钥	36
`requester_profile_key`	uuidv4	钱包的唯一标识密钥	36
`bank_slip_key`	uuidv4	Boleto 的唯一标识密钥	36

请求体

{
  "beneficiary_settlement_percentage": 70,
  "split_payment_rules": [
    {
      "percentage": 20,
      "document_number": "12345678901",
      "account_owner_name": "John Smith",
      "account_number": "1234567",
      "account_digit": "8"
    },
    {
      "percentage": 10,
      "document_number": "10987654321",
      "account_owner_name": "Mary Johnson",
      "account_number": "7654321",
      "account_digit": "0"
    }
  ]
}

请求体参数

字段	类型	描述	字符数
`beneficiary_settlement_percentage` *	float	分配给 Boleto 受益人的结算金额百分比，取值范围 0 至 100	-
`beneficiary_max_amount`	float	受益人在结算时可获得的最大金额。当付款金额超过此限额时，超出部分将全部分配给 `split_payment_rules` 数组中的第一条规则。取值大于 0 且不大于 Boleto 金额	-
`split_payment_rules` *	object array	分账规则列表。最少 1 条，最多 10 条	split_payment_rule 对象

split_payment_rule 对象

字段	类型	描述	字符数
`percentage` *	float	分配给该账户的结算金额百分比，取值范围 0 至 100。当此规则专门用于接收 `beneficiary_max_amount` 之上的超出部分时，请使用 `0`	-
`document_number` *	string	目标账户持有人的 CPF/CNPJ	11 或 14
`account_owner_name` *	string	目标账户持有人姓名	100
`account_number` *	string	目标账户号	20
`account_digit` *	string	目标账户校验位	2

用例：将逾期利息和滞纳金导向单独账户

如何配置分账，使超出 Boleto 面值的利息和滞纳金被导向与受益人不同的账户？

此场景常见于代第三方（学校、物业、市场平台等）发行 Boleto 的平台：Boleto 持有人始终应收取面值，而平台则在逾期付款时获得额外的利息/滞纳金。

通过 beneficiary_max_amount 与一条 percentage = 0 的分账规则配合实现：

{
  "beneficiary_settlement_percentage": 100,
  "beneficiary_max_amount": 1000.00,
  "split_payment_rules": [
    {
      "percentage": 0,
      "document_number": "12345678000199",
      "account_owner_name": "收款平台",
      "account_number": "1234567",
      "account_digit": "8"
    }
  ]
}

计算方式（以 R$ 1.000,00 的 Boleto 为例）：

场景	已付金额	受益人收到	平台收到
按时付款	R$ 1.000,00	R$ 1.000,00	R$ 0,00（不生成结算）
逾期付款（含 R$ 100,00 利息/滞纳金）	R$ 1.100,00	R$ 1.000,00	R$ 100,00
部分逾期付款	R$ 950,00	R$ 950,00	R$ 0,00

规则：受益人最多收到 beneficiary_max_amount；超过该限额的金额将全部分配给 split_payment_rules 中的第一条规则。

注意！

beneficiary_max_amount 必须大于 0 且不大于 Boleto 金额（amount）。
当任一规则的 percentage = 0 时，必须填写 beneficiary_max_amount。
每张 Boleto 仅允许 split_payment_rules 中一条规则的 percentage = 0（即超出部分的接收方）。

Response

状态码

204

响应体

{}

错误响应

状态码

4xx

响应体：错误

{
  "title": "标题",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "代码",
  "extra_fields": {}
}

HTTP 状态码 `status`	QI 代码 `code`	标题 `title`	英文描述 `description`	葡语描述 `translation`
400	QIT000001	Bad Request	Schema Error	Schema Inválido
404	BKS000029	Not Found	Bank slip not found for the given key (`{bank_slip_key}`).	Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).
400	BKS000032	Bad Request	Bank slip must be in 'registered' status.	O boleto deve possuir o status 'registered'.
422	BKS000157	Unprocessable Entity	Could not find an account matching the provided split payment account data.	Não foi possível encontrar uma conta com os dados informados na regra de split payment.
400	BKS000158	Bad Request	The beneficiary_max_amount must be greater than 0 and not greater than the bank slip amount.	O beneficiary_max_amount deve ser maior que 0 e não pode ser maior que o valor do boleto.
400	BKS000159	Bad Request	Split payment rules with percentage equal to 0 require beneficiary_max_amount to be set.	Regras de split payment com percentual igual a 0 exigem o campo beneficiary_max_amount preenchido.
400	BKS000160	Bad Request	Only one split payment rule with percentage equal to 0 is allowed.	É permitido apenas uma regra de split payment com percentual igual a 0.

Request​

路径参数​

请求体参数​

split_payment_rule 对象​

用例：将逾期利息和滞纳金导向单独账户​

Response​

错误响应​