Regras de Negócio — Amortização Extraordinária

Esta página consolida as invariantes que governam a criação, a liquidação e o cancelamento de uma amortização extraordinária. Consulte-a sempre que as páginas de endpoints citarem um código de erro, um campo ou uma condição que precise de contexto adicional.

Data de referência (reference_date)

A reference_date é fornecida pelo chamador na requisição de criação e é a única referência temporal usada pelo serviço — o sistema nunca usa date.today(). Toda lógica dependente de data (classificação de parcelas vencidas, desconto pro-rata do Valor Presente, seleção de parcelas elegíveis para early_amortization e nominal_amount) parte desse campo. A consulta de Valor Presente ao security-service recebe essa mesma reference_date.

Tipos de amortização

Os 7 tipos suportados e como cada um distribui o amount entre as parcelas de installment_list:

Tipo	Regra de distribuição entre as parcelas selecionadas	Permite pagamento parcial
equal_amount	Proporcional ao Valor Presente, vencidas primeiro e depois futuras	Não
first_installments	Sequencial nas N primeiras parcelas selecionadas (por vencimento), N = number_of_installments	Não
present_amount	Explícita por parcela; desconto ordena juros → multa → principal	Não
matured_installments	Apenas parcelas já vencidas, em ordem de vencimento	Não
early_amortization	Uma única parcela futura, até o Valor Presente	Sim
nominal_amount	Parcelas futuras pelo valor nominal (principal + juros), em ordem de vencimento, sem Valor Presente	Sim
full_amortization	Proporcional ao Valor Presente entre todas as parcelas selecionadas, sem cascata; cada parcela é quitada integralmente	Não

installment_list (array de installment_number inteiros) é obrigatório para todos os tipos — omiti-lo retorna EVC100002. O serviço resolve cada installment_number para a parcela correspondente da security e consulta o Valor Presente por parcela selecionada; o amortization_type define apenas como o amount é distribuído entre essas parcelas.

Amortização antecipada (early_amortization)

early_amortization permite pagamento parcial (assim como nominal_amount). Todas as seguintes condições se aplicam:

• Exatamente 1 parcela em installment_list — caso contrário, EVC100015.
• A parcela-alvo não pode estar vencida — caso contrário, EVC100016.
• O amount deve ser ≤ Valor Presente da parcela — caso contrário, EVC100017.
• Pagamento parcial é permitido. O estado paid_amount > 0 AND paid_amount < expected_amount é derivado das colunas; não há novo valor de enum de status. pending_conciliation representa tanto "não pago" quanto "parcialmente pago"; a transição para paid só ocorre quando total_paid_amount >= total_expected_amount - tolerance_amount.

Amortização pelo valor nominal (nominal_amount)

nominal_amount quita parcelas futuras pelo valor nominal — principal mais juros no vencimento — sem trazê-las ao Valor Presente da reference_date. Todas as seguintes condições se aplicam:

• Todas as parcelas em installment_list devem ter due_date maior ou igual à reference_date — parcela vencida retorna EVC100030.
• O amount é distribuído em ordem de vencimento, cobrindo cada parcela pelo valor nominal até se esgotar; a última parcela alcançada pode receber valor parcial.
• O amount deve ser ≤ soma dos valores nominais das parcelas selecionadas — caso contrário, EVC100031.
• Pagamento parcial é permitido na liquidação, com o mesmo estado derivado descrito para early_amortization.

Amortização integral (full_amortization)

full_amortization usa o amount informado para quitar todas as parcelas de installment_list, independentemente do Valor Presente de cada uma:

• O amount é rateado entre as parcelas proporcionalmente ao Valor Presente na reference_date, sem cascata: parcela com Valor Presente positivo recebe cota positiva, e parcela com Valor Presente 0 recebe cota 0 (veja Parcelas com Valor Presente 0).
• Cada event_conciliation nasce com expected_amount igual à sua cota e discount_amount igual à diferença entre o Valor Presente e a cota.
• O amount não pode exceder a soma dos Valores Presentes das parcelas selecionadas — caso contrário, EVC100035.
• Na liquidação, o pagamento da cota dá baixa integral na parcela no security-service: o valor pago é registrado como pago e o que falta para quitar a parte do investidor, como desconto. Com investidor único, o desconto cobre todo o saldo restante da parcela, que termina zerada. O mesmo vale para present_amount.

Parcelas com Valor Presente 0

Na reference_date, a primeira parcela a vencer vale principal e juros descontados pro-rata; as demais parcelas futuras valem apenas o principal. Em um ativo com carência, as parcelas só de juros (principal 0) que vencem depois da primeira têm, por isso, Valor Presente 0 e recebem cota 0 no rateio.

Cada parcela de installment_list com Valor Presente exatamente 0 gera um event_conciliation com expected_amount 0 e discount_amount 0 — a parcela é quitada sem pagamento — quando todas as condições abaixo são atendidas:

• o ativo tem um único investidor, que detém todas as cotas integralizadas;
• o ativo não é liquidado via CETIP;
• o investidor é liquidado pelo novo sistema interno da QI Tech (internal_new_system);
• a parcela está em aberto (installment_status diferente de paid, paid_early, paid_overdue e canceled) e vence depois da reference_date;
• installment_list inclui todas as parcelas em aberto que ainda têm principal (principal_amortization_amount maior que 0).

Duas regras amarram essas parcelas ao principal em aberto:

1. Regra 1 — parcela com Valor Presente 0 exige todo o principal. Em ativo com investidor único e fora da CETIP, se installment_list traz parcela com Valor Presente 0 em aberto e com vencimento depois da reference_date, mas deixa de fora alguma parcela em aberto com principal, a criação é rejeitada com EVC100037, que lista as parcelas faltantes.
2. Regra 2 — todo o principal exige as parcelas com Valor Presente 0. Se a requisição quita todo o principal em aberto de um ativo com investidor único, fora da CETIP e com investidor no novo sistema, installment_list também precisa incluir todas as parcelas em aberto com Valor Presente 0 que vencem depois da reference_date — caso contrário, EVC100038, que lista as parcelas faltantes.

O serviço nunca acrescenta parcelas por conta própria: o integrador lista o que está quitando. Nos demais casos — ativo com mais de um investidor ou liquidado via CETIP, investidor fora do novo sistema (como o sistema legado, internal_legacy_system), parcela já quitada ou cancelada, vencida ou que vence na própria reference_date — a parcela com Valor Presente 0 é rejeitada com EVC100034. A ordem das verificações está em Consistência entre amount e a distribuição.

Consistência entre amount e a distribuição

Após distribuir o amount, o serviço valida o resultado nesta ordem; as verificações 2 e 3 são feitas juntas, parcela a parcela. As verificações 3, 6 e 7 são exclusivas de full_amortization; as demais valem para todos os tipos:

1. amount maior que a soma dos Valores Presentes das parcelas distribuídas → EVC100035 (tipos precificados a Valor Presente; early_amortization e nominal_amount mantêm EVC100017 e EVC100031).
2. Alguma parcela selecionada ficaria com expected_amount igual a zero → EVC100034; selecione apenas parcelas que o amount cubra. A única exceção é a parcela com Valor Presente 0 de full_amortization em ativo com investidor único e fora da CETIP, desde que esteja em aberto e vença depois da reference_date (veja Parcelas com Valor Presente 0).
3. A parcela com Valor Presente 0 da exceção acima está em installment_list, mas falta alguma parcela em aberto com principal (regra 1) → EVC100037, com a lista das parcelas faltantes.
4. A soma dos expected_amount distribuídos difere do amount em mais de R$ 0,01 → EVC100033. Em present_amount, o amount precisa ser igual à soma dos Valores Presentes menos o total_discount.
5. Os expected_amount são arredondados para centavos, com o resíduo de arredondamento na última parcela com expected_amount positivo. Toda parcela, exceto as quitadas sem pagamento, precisa continuar com expected_amount positivo depois do arredondamento — caso contrário, EVC100034.
6. A requisição quita todo o principal em aberto, mas não lista todas as parcelas em aberto com Valor Presente 0 que vencem depois da reference_date (regra 2) → EVC100038, com a lista das parcelas faltantes. Só se aplica a ativo com investidor único, fora da CETIP, e a investidor no novo sistema.
7. Parcela com Valor Presente 0 de investidor que não é liquidado pelo novo sistema → EVC100034.

Assim, total_expected_amount do evento é sempre igual à soma dos filhos, e as parcelas quitadas sem pagamento permanecem com expected_amount 0.

Fluxo de liquidação

Orquestração interna. A liquidação dos eventos extraordinários é executada pela QI Tech (account-liquidation-api) ao detectar o pagamento — o integrador não chama nenhum endpoint nesta etapa, nem recebe webhook dedicado às transições de status. As regras abaixo descrevem o comportamento interno para você entender o que ocorre após a criação.

Liquidação ordinária emite o total completo (regra 4). A liquidação ordinária na due_date continua emitindo o total_amount completo da parcela via SQS; não há subtração do paid_amount. O evento reconcilia o estado parcial-pago no seu próprio engine de early_amortization.

Parcelas com expected_amount 0 são quitadas por último, sem transferência. Em full_amortization, a QI Tech liquida primeiro as parcelas com expected_amount positivo, conforme os pagamentos entram. Só depois que todas elas estão pagas, cada parcela com expected_amount 0 é liquidada internamente com valor 0 — sem transferência de recursos e sem envio de liquidação à QI DTVM — e o security-service a quita integralmente, com desconto de todo o saldo da parcela. Pela liquidação, o evento só passa a paid quando todas as parcelas, inclusive as de valor 0, estão quitadas. Com as parcelas de valor positivo já pagas, o evento também não é finalizado enquanto restar parcela de valor 0 por quitar; se ele for finalizado com alguma parcela de valor positivo ainda sem pagamento, as parcelas de valor 0 são canceladas junto com as demais parcelas não pagas. Quando a liquidação quita toda a dívida, o ativo passa a matured.

Cancelamento e finalização

Orquestração interna. Cancelamento e finalização são disparados por uma rotina diária e — o integrador não chama nenhum endpoint para cancelar ou finalizar uma amortização extraordinária, e não há webhook tenant-facing dedicado a essas transições. A descrição abaixo é informativa.

Veja também

• Conceito
• Roteiro de Integração
• Criar Amortização Extraordinária
• Consultar Amortização Extraordinária
• Recompra de Operação
• Exemplos
• Catálogo de erros