跳到主要内容

Exemplos — Amortização Extraordinária

Esta página apresenta dois 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.

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) ou itens não inteiros 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.
  • 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​