Pular para o conteúdo principal

Atualização de Rateio de Crédito

Este endpoint permite atualizar o rateio de crédito (split de pagamento) de um boleto previamente emitido. As novas regras substituem integralmente as anteriores e passam a valer para a próxima liquidação do boleto.

Atenção!
  • O boleto precisa estar com o status registered e ainda não pago.
  • A soma de beneficiary_settlement_percentage com os percentuais de cada item de split_payment_rules deve ser exatamente igual a 100.
  • O envio do payload substitui todas as regras de rateio existentes (não é incremental).
  • O rateio passa a valer para todos os fluxos de liquidação do boleto (SILOC, STR, cartório e Pix QR Code), inclusive em boletos com QR Code já emitido — neste caso, as regras também serão atualizadas no QR Code automaticamente.
  • As contas das regras de rateio precisam estar abertas e cadastradas na QI Tech (a QI Tech consultará pelo document_number, account_number e account_digit informados).

Request​

ENDPOINT
/v2/bank_slip/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip/BANK_SLIP_KEY/split_payment
MÉTODO
PUT

Path parameters​

CampoTipoDescriçãoCaracteres
account_keyuuidv4Chave única de identificação da conta em que o boleto foi emitido36
requester_profile_keyuuidv4Chave única de identificação da carteira36
bank_slip_keyuuidv4Chave única de identificação do boleto36
Request Body
{
  "beneficiary_settlement_percentage": 70,
  "split_payment_rules": [
    {
      "percentage": 20,
      "document_number": "12345678901",
      "account_owner_name": "João da Silva",
      "account_number": "1234567",
      "account_digit": "8"
    },
    {
      "percentage": 10,
      "document_number": "10987654321",
      "account_owner_name": "Maria Souza",
      "account_number": "7654321",
      "account_digit": "0"
    }
  ]
}

Request Body Params​

CampoTipoDescriçãoCaracteres
beneficiary_settlement_percentage *floatPercentual do valor liquidado destinado ao beneficiário do boleto. Aceita valor de 0 a 100-
beneficiary_max_amountfloatValor máximo que o beneficiário recebe na liquidação. Quando o valor pago exceder este limite, o excedente é direcionado integralmente para a primeira regra do array split_payment_rules. Aceita valor maior que 0 e menor ou igual ao valor do boleto-
split_payment_rules *object arrayLista de regras de rateio. Mínimo 1, máximo 10 regrasObjeto split_payment_rule

Objeto split_payment_rule​

CampoTipoDescriçãoCaracteres
percentage *floatPercentual do valor liquidado destinado a esta conta. Aceita valor de 0 a 100. Use 0 quando esta regra for destinada exclusivamente a receber o excedente do beneficiary_max_amount-
document_number *stringCPF/CNPJ do titular da conta destino11 ou 14
account_owner_name *stringNome do titular da conta destino100
account_number *stringNúmero da conta destino20
account_digit *stringDígito verificador da conta destino2

Caso de uso: receber juros e multa em uma conta separada​

Como configurar para que o juros e multa que excederem o valor de face do boleto sejam direcionados a uma conta diferente do beneficiário?

Esse cenário é comum em plataformas que emitem boletos em nome de terceiros (escolas, condomínios, marketplaces), onde o titular do boleto deve receber sempre o valor de face e a plataforma fica com a parcela adicional de juros/multa em casos de pagamento em atraso.

A configuração é feita combinando beneficiary_max_amount com uma regra de rateio com percentage = 0:

{
  "beneficiary_settlement_percentage": 100,
  "beneficiary_max_amount": 1000.00,
  "split_payment_rules": [
    {
      "percentage": 0,
      "document_number": "12345678000199",
      "account_owner_name": "Plataforma de Cobrança",
      "account_number": "1234567",
      "account_digit": "8"
    }
  ]
}

Como o cálculo funciona considerando um boleto de R$ 1.000,00:

CenárioValor pagoBeneficiário recebePlataforma recebe
Pagamento em diaR$ 1.000,00R$ 1.000,00R$ 0,00 (sem settlement gerado)
Pagamento em atraso (com R$ 100,00 de juros/multa)R$ 1.100,00R$ 1.000,00R$ 100,00
Pagamento parcial em atrasoR$ 950,00R$ 950,00R$ 0,00

A regra é: o beneficiário recebe no máximo beneficiary_max_amount; qualquer valor pago acima disso é direcionado integralmente para a primeira regra de split_payment_rules.

Atenção!
  • beneficiary_max_amount deve ser maior que 0 e menor ou igual ao valor do boleto (amount).
  • Quando alguma regra tem percentage = 0, o campo beneficiary_max_amount é obrigatório.
  • Apenas uma regra de split_payment_rules pode ter percentage = 0 por boleto (a destinatária do excedente).

Response​

STATUS
204
Response Body
{}

Error Response​

STATUS
4xx
Response Body: Error
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
Código HTTP
status		Código QI
code		Título
title		Descrição (eng)
description		Descrição (pt-br)
translation
400QIT000001Bad RequestSchema ErrorSchema Inválido
404BKS000029Not FoundBank slip not found for the given key ({bank_slip_key}).Boleto não encontrado para a chave fornecida ({bank_slip_key}).
400BKS000032Bad RequestBank slip must be in 'registered' status.O boleto deve possuir o status 'registered'.
422BKS000157Unprocessable EntityCould 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.
400BKS000158Bad RequestThe 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.
400BKS000159Bad RequestSplit 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.
400BKS000160Bad RequestOnly one split payment rule with percentage equal to 0 is allowed.É permitido apenas uma regra de split payment com percentual igual a 0.