Do ativo ao boleto

Quando a configuração de cessão tem cobrança por boleto, a QI Tech registra automaticamente um boleto na QI SCD para cada direito creditório cedido. Os dados do boleto vêm do que você enviou na inserção do ativo. Esta página mostra de onde vem cada campo e quais deles você usa para identificar e conciliar o boleto no seu sistema.

Vale para os direitos creditórios duplicata mercantil, duplicata de serviços, CT-e e contrato descontado. Cada ativo gera um boleto. No contrato descontado, como cada ativo é uma parcela, cada parcela tem o seu boleto.

Quando o boleto é registrado

O boleto não é registrado na inserção do ativo. Ele é registrado depois que a cessão é paga, quando o ativo entra na carteira do fundo. A confirmação do registro chega no processamento do retorno bancário do dia útil seguinte. O fluxo completo está em Boletos — Início.

Por isso, os campos do boleto precisam estar certos já na inserção. Depois que o ativo é cedido, alterações no boleto (vencimento, juros, multa, abatimento) são feitas pelas instruções de boleto, não reenviando o ativo.

Vencimento do boleto não é vencimento do ativo

A instrução de alteração de vencimento muda só o boleto. O ativo continua com o vencimento original na carteira do fundo, no relatório de estoque e na contagem de atraso. Para mudar também o vencimento do ativo, informe uma prorrogação (asset_extension, com new_maturity_date) na liquidação de ativos. A prorrogação vale para direitos creditórios, inclusive o contrato descontado, e não existe para o contrato parcelado.

De onde vem cada campo

Os caminhos abaixo são relativos ao objeto discounted_credit_right do corpo da requisição de inserção.

Campos de controle do cliente

São os campos que você escolhe livremente e que voltam na consulta do boleto. Use-os para ligar o boleto ao registro do seu sistema.

Campo do ativo	Campo do boleto	Regra
participant_control_number	Número de controle do participante	Até 25 caracteres. Só letras, números e _ são mantidos; os demais caracteres são removidos. Precisa ser único na carteira de cobrança.
order_number	Número do documento (seu número)	O boleto recebe apenas os 10 últimos caracteres. O valor completo continua no ativo.
bankslip.our_number.number	Nosso número	Opcional. Envie só quando a sua carteira de cobrança prevê nosso número emitido pelo cliente. Sem ele, o nosso número é gerado no registro.

Envie sempre o participant_control_number em cessão com boleto

Na inserção do ativo o campo é opcional, mas na cobrança ele é a chave do boleto: a carteira de cobrança não aceita dois boletos com o mesmo número de controle, e ativos sem o campo contam como repetidos entre si. Na prática, só o primeiro ativo sem número de controle tem boleto registrado. Gere um valor único por ativo, com até 25 caracteres alfanuméricos — por exemplo, derivado do seu external_id.

Valor, vencimento e encargos

Campo do ativo	Campo do boleto	Regra
face_value	Valor do boleto
maturity_date	Vencimento
delay.fine	Multa	Precisa ser percentual (fine_type: percentage). Multa com percentage_value igual a zero não entra no boleto.
delay.interest.pre_fixed	Juros de mora	Cobrados por dia de atraso, em valor: face_value × taxa diária. Se você enviar monthly_rate, ela é convertida em taxa diária simples na calendar_base informada. Taxa igual a zero não entra no boleto.

Se o ativo não trouxer delay, o boleto usa a multa e os juros cadastrados na configuração de cobrança do fundo.

Pagador e sacador

Origem	Campo do boleto	Regra
borrower.name, borrower.document_number, borrower.person_type	Pagador	O documento vai sem pontuação.
borrower.address	Endereço do pagador	Só vai para o boleto se estiverem preenchidos street, number, neighborhood, postal_code, city e uf. Faltando qualquer um, o boleto é registrado sem endereço. complement é opcional.
Cedente da configuração de cessão	Sacador/avalista	Vem do cadastro do cedente, não do corpo da requisição. Aparece quando a carteira de cobrança prevê o cedente como sacador.

Campos que não vão para o boleto

Estes campos ficam no ativo e voltam na consulta do ativo, mas não aparecem no boleto:

• external_id — use o participant_control_number como ponte entre o boleto e o ativo;
• installment_number;
• o objeto contract do contrato descontado (number, issue_date, total_face_value, number_of_installments);
• o objeto invoice das duplicatas e do CT-e.

Exemplo

Trecho de um contrato descontado inserido numa cessão com boleto:

{
    "discounted_credit_right": {
        "external_id": "parcela-958431587-01",
        "face_value": 1231.21,
        "maturity_date": "2025-12-10",
        "installment_number": 1,
        "participant_control_number": "CT958431587P01",
        "order_number": "2023000958431587",
        "delay": {
            "fine": { "fine_type": "percentage", "percentage_value": 0.02 },
            "interest": {
                "method": "pre_fixed",
                "pre_fixed": { "monthly_rate": 0.01, "calendar_base": "calendar_360" }
            }
        }
    }
}

O boleto registrado na QI SCD fica assim:

Campo do boleto	Valor	Por quê
Valor	R$ 1.231,21	face_value
Vencimento	10/12/2025	maturity_date
Número de controle do participante	CT958431587P01	participant_control_number, como enviado (só tem letras e números)
Número do documento	0958431587	os 10 últimos caracteres de order_number
Multa	2%	fine.percentage_value de 0,02
Juros de mora	R$ 0,41 por dia de atraso	1% ao mês × 12 ÷ 360 dias × R$ 1.231,21

Nem external_id, nem installment_number, nem o objeto contract aparecem no boleto. Para achar o ativo a partir do boleto, use o número de controle do participante.

Conferindo o boleto

Consulte o boleto registrado em Recuperando Boleto e Segunda Via. A resposta traz os dois números de controle:

• external_participant_control_number — o valor exatamente como você enviou;
• participant_control_number — o valor depois da limpeza de caracteres, que é o que está no boleto.

Para avisos de registro, pagamento e baixa, veja os webhooks de boleto.