Pular para o conteúdo principal

Exemplos — Amortização Extraordinária

Esta página apresenta cinco cenários de criação. A interação do integrador é fire-and-forget: realiza apenas a chamada de criação e a QI Tech orquestra liquidação, finalização e cancelamento internamente. Não há webhook tenant-facing dedicado às transições de status do event_conciliation extraordinário; a confirmação do efeito da operação é observada via os relatórios e webhooks já existentes para a operação subjacente (ex.: commercial_paper.operation_status_change).

Cenário 1: quitação antecipada parcial de uma parcela (early_amortization)​

Cobre uma única parcela futura, com pagamento parcial permitido.

POST /event_conciliation/extraordinary_event

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "early_amortization",
  "amount": 1500.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [3]
}

Resposta: 201 Created

{
  "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111",
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "amortization_type": "early_amortization",
  "total_expected_amount": 1500.00,
  "total_discount_amount": 0,
  "status": "pending_conciliation",
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "event_conciliation_list": [
    {
      "event_conciliation_key": "22222222-2222-4222-8222-222222222222",
      "installment_key": "33333333-3333-4333-8333-333333333333",
      "expected_amount": 1500.00,
      "discount_amount": 0,
      "due_date": "2026-04-24",
      "status": "pending_conciliation",
      "event_conciliation_type": "extraordinary"
    }
  ]
}

A partir desse 201 a integração está concluída do lado do integrador. Quando o pagamento de R$ 1.500,00 atingir a conta de liquidação correspondente, a QI Tech (account-liquidation-api) liquida o evento de conciliação da parcela internamente e atualiza o paid_amount; quando a soma cobre total_expected_amount - tolerance_amount, o parent transita para paid. Se o pagamento não entrar, o evento é cancelado ou finalizado pela rotina diária de settlement do security-service.

Cenário 2: quitação total com desconto (present_amount com 2 installments)​

Cria uma amortização com desconto consolidado cobrindo duas parcelas.

POST /event_conciliation/extraordinary_event

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "present_amount",
  "amount": 5000.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1, 2],
  "total_discount": 100.00
}

Resposta 201 Created — dois eventos de conciliação da parcela são gerados com os valores distribuídos conforme o engine de present_amount (juros → multa → principal). Veja Criar Amortização Extraordinária para o shape completo da resposta.

A partir do 201 a interação do integrador é a mesma do Cenário 1: a QI Tech liquida cada evento de conciliação da parcela quando os pagamentos correspondentes entram, e finaliza ou cancela o evento internamente caso os valores não cheguem dentro da janela de settlement.

Cenário 3: quitação de parcelas futuras pelo valor nominal (nominal_amount)​

Emissor quer quitar as parcelas 3 e 4 antes do vencimento pagando o valor nominal de cada uma (principal + juros no vencimento), sem desconto a Valor Presente. A reference_date é anterior ao vencimento de ambas.

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "nominal_amount",
  "amount": 18670.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-06-06",
  "installment_list": [3, 4]
}

Resposta 201 Created — um evento de conciliação da parcela por parcela, com expected_amount igual ao valor nominal de cada uma (9360.00 e 9310.00 neste exemplo). Se o amount fosse menor que a soma, a parcela 3 seria coberta primeiro e a parcela 4 receberia o restante. Parcelas vencidas retornam EVC100030; amount acima da soma dos valores nominais retorna EVC100031. A liquidação aceita pagamento parcial, como em early_amortization.

Cenário 4: quitação integral com valor negociado (full_amortization)​

Emissor e investidor acordam quitar as parcelas 1 e 2 por R$ 10.000,00, embora os Valores Presentes na reference_date sejam R$ 9.460,00 e R$ 9.410,00. O amount é rateado proporcionalmente ao Valor Presente e cada parcela é quitada integralmente na liquidação.

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "full_amortization",
  "amount": 10000.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-02-08",
  "installment_list": [1, 2]
}

Resposta 201 Created — dois eventos de conciliação da parcela com expected_amount 5013.25 e 4986.75 (a soma é igual ao amount) e discount_amount 4446.75 e 4423.25. Um amount acima da soma dos Valores Presentes retorna EVC100035; um amount pequeno demais para dar cota positiva a todas as parcelas retorna EVC100034.

Cenário 5: quitação integral de ativo com carência (full_amortization)​

Um ativo pré-fixado de R$ 30.000,00 tem quatro parcelas trimestrais, juros de 6% ao trimestre e todo o principal na parcela 4 — as parcelas 1 a 3 são de carência e pagam só juros. O ativo tem um único investidor, detentor de todas as cotas integralizadas, não é liquidado via CETIP e o investidor é liquidado pelo novo sistema interno. Emissor e investidor acordam quitar toda a dívida por R$ 31.500,00 em 2026-02-20, antes do vencimento da parcela 1. Nessa reference_date, as parcelas valem:

ParcelaVencimentoPrincipalJurosValor Presente
12026-03-10R$ 0,00R$ 1.800,00R$ 1.780,13
22026-06-10R$ 0,00R$ 1.800,00R$ 0,00
32026-09-10R$ 0,00R$ 1.800,00R$ 0,00
42026-12-10R$ 30.000,00R$ 1.800,00R$ 30.000,00

A parcela 1, a primeira a vencer, vale seus juros descontados até a reference_date; as demais valem só o principal. Por isso as parcelas 2 e 3 têm Valor Presente 0 e são quitadas sem pagamento, nas condições descritas em Regras de Negócio. A requisição lista todas as parcelas em aberto:

{
  "security_key": "55555555-5555-4555-8555-555555555555",
  "investment_key": "<investment_key>",
  "amortization_type": "full_amortization",
  "amount": 31500.00,
  "reference_date": "2026-02-20",
  "due_date": "2026-02-20",
  "installment_list": [1, 2, 3, 4]
}

Resposta 201 Created — quatro eventos de conciliação da parcela, com total_expected_amount 31500.00:

Parcelaexpected_amountdiscount_amount
11764.4415.69
20.000.00
30.000.00
429735.56264.44

A QI Tech liquida primeiro as parcelas 1 e 4, conforme os pagamentos entram; com as duas pagas, quita internamente as parcelas 2 e 3 com valor 0, sem transferência. O evento passa a paid quando as quatro parcelas estão quitadas e, com toda a dívida liquidada, o ativo passa a matured.

Duas variações dessa requisição são rejeitadas. Com installment_list [1, 2] e amount 1700.00, a requisição traz a parcela 2, de Valor Presente 0, sem quitar o principal da parcela 4 — 400 Bad Request:

{
  "title": "Bad Request",
  "description": "Installment 2 has present value 0 and can only be settled with 0 when the request settles all outstanding principal. Missing installments: [4].",
  "translation": "A parcela 2 tem valor presente 0 e so pode ser liquidada com 0 quando a solicitacao quita todo o principal em aberto. Parcelas faltantes: [4].",
  "code": "EVC100037"
}

Com installment_list [1, 4] e o mesmo amount 31500.00, a requisição quita todo o principal em aberto, mas deixa de fora as parcelas 2 e 3 — 400 Bad Request:

{
  "title": "Bad Request",
  "description": "The request settles all outstanding principal and must also list the installments with present value 0 due after the reference date. Missing installments: [2, 3].",
  "translation": "A solicitacao quita todo o principal em aberto e deve listar tambem as parcelas com valor presente 0 que vencem depois da data de referencia. Parcelas faltantes: [2, 3].",
  "code": "EVC100038"
}

O serviço não acrescenta parcelas por conta própria: liste em installment_list tudo o que a requisição quita.

Troubleshooting​

Códigos de erro mais comuns ao chamar a criação. Para a lista completa, consulte o Catálogo de erros.

  • EVC100015 (400, EarlyAmortizationRequiresSingleInstallment) — early_amortization aceita exatamente uma parcela em installment_list. Reduza para 1.
  • EVC000007 (404, InstallmentNumberNotFound) — algum installment_number enviado em installment_list não existe na security alvo. Confira os números retornados em GET /security/security/{security_key} antes de chamar.
  • QIT000001 (400) — schema rejeitado. Causa típica: enviar o campo legado installment_key_list (removido), itens não inteiros ou números repetidos em installment_list.
  • EVC100016 (400, EarlyAmortizationInstallmentOverdue) — a parcela alvo de early_amortization está vencida e não é elegível. Selecione uma parcela futura.
  • EVC100017 (400, EarlyAmortizationAmountExceedsPresentValue) — em early_amortization, o amount excedeu o Valor Presente da parcela. Confirme o PV antes de chamar.
  • EVC100030 (400, InstallmentNotEligibleForNominalAmortization) — em nominal_amount, alguma parcela de installment_list já está vencida na reference_date. Selecione apenas parcelas futuras.
  • EVC100031 (400, NominalAmountExceedsInstallmentsNominalValue) — em nominal_amount, o amount excedeu a soma dos valores nominais (principal + juros) das parcelas selecionadas. Reduza o amount.
  • EVC100033 (400, DistributionDoesNotMatchAmount) — a soma dos expected_amount distribuídos difere do amount informado em mais de R$ 0,01. Em present_amount, envie amount igual à soma dos Valores Presentes menos o total_discount.
  • EVC100034 (400, DistributionWithZeroInstallment) — alguma parcela selecionada ficaria com expected_amount zero, inclusive após o arredondamento para centavos (por exemplo, total_discount igual ao Valor Presente, ou amount que se esgota antes da última parcela). Selecione apenas parcelas que o amount cubra. Em full_amortization, parcela com Valor Presente 0 também retorna este código quando o ativo tem mais de um investidor ou é liquidado via CETIP, quando o investidor não é liquidado pelo novo sistema ou quando a parcela já está quitada ou cancelada, vencida ou vence na reference_date.
  • EVC100035 (400, AmountExceedsInstallmentsPresentValue) — o amount excede a soma dos Valores Presentes das parcelas selecionadas. Reduza o amount.
  • EVC100037 (400) — em full_amortization, installment_list traz parcela com Valor Presente 0, mas deixa de fora parcela em aberto com principal. Inclua as parcelas listadas na mensagem ou retire de installment_list as parcelas com Valor Presente 0: elas só são quitadas sem pagamento quando a requisição quita todo o principal em aberto.
  • EVC100038 (400) — em full_amortization, 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. Inclua as parcelas listadas na mensagem; o serviço não as acrescenta por conta própria.
  • EVC100013 (424, SecurityApiUnavailable) — Security API temporariamente indisponível ao buscar o Valor Presente; é transitório. Aguarde e repita a chamada.
  • SEC000031 (400, PostFixedSecurityNotSupported) — ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1. Use ativos pre_price ou pre_sac.

Veja também​