Criar Amortização Extraordinária

Este endpoint cria uma amortização extraordinária sobre um ou mais installment de uma emissão. O event-conciliation-service agrupa as parcelas em um evento extraordinário de amortização único, distribui o amount declarado conforme o amortization_type informado e obtém o Valor Presente via security-service — o integrador não calcula Valor Presente no seu lado. A reference_date é fornecida pelo chamador na requisição da amortização extraordinária e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata.

Request

ENDPOINT

/event_conciliation/extraordinary_event

MÉTODO

POST

Request Body

installment_list (array de installment_number, inteiros ≥ 1 e sem repetição) é obrigatório para todos os tipos: ele define as parcelas-alvo e o amortization_type define como o amount é distribuído entre elas. Os números enviados em installment_list são resolvidos pelo serviço contra installment_number da security correspondente.

Exemplo — early_amortization (uma parcela futura):

{
  "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": [1]
}

Exemplo — equal_amount (proporcional entre as parcelas selecionadas):

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

Exemplo — nominal_amount (parcelas futuras pelo valor nominal):

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

Request Body Params

Campo	Tipo	Obrigatório	Descrição
`security_key`	string (UUID)	Sim	Chave única do ativo (`security`) sobre o qual a amortização será aplicada.
`investment_key`	string (UUID)	Sim	Chave do investimento alvo. Usado pelo security-service como base proporcional no cálculo de Valor Presente.
`amortization_type`	string	Sim	Estratégia de distribuição. Valores: `equal_amount`, `first_installments`, `present_amount`, `matured_installments`, `early_amortization`, `nominal_amount`, `full_amortization`.
`amount`	number	Sim	Valor total a ser amortizado (em BRL). Distribuído entre as parcelas selecionadas conforme o `amortization_type`.
`reference_date`	string (date)	Sim	Data de referência em formato `YYYY-MM-DD`. Fornecida pelo chamador — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente.
`due_date`	string (date)	Sim	Data alvo de liquidação (tipicamente igual à `reference_date`).
`installment_list`	array de inteiros (≥ 1)	Sim	Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1` e sem números repetidos (`uniqueItems`) — repetir um número retorna `QIT000001` (400). Obrigatório para todos os tipos — omitir retorna `EVC100002`. O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`. O legado `installment_key_list` foi removido — clientes que ainda enviarem o campo recebem `QIT000001` (400). Em `full_amortization`, as parcelas com Valor Presente 0 seguem regras próprias — veja Regras de Negócio.
`total_discount`	number	Não	Utilizado apenas com `present_amount` — distribui o desconto na ordem juros → multa → principal.
`number_of_installments`	integer	Condicional	Obrigatório com `first_installments`: quantas das parcelas selecionadas, em ordem de vencimento, recebem o valor.

Response

STATUS

201

Response Body

{
  "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"
    }
  ]
}

Response Body Params

Campo	Tipo	Descrição
`extraordinary_event_conciliation_key`	string (UUID)	Chave do evento geral de amortização extraordinário criado.
`security_key`	string (UUID)	Chave do ativo — ecoa o valor enviado.
`amortization_type`	string	Tipo de amortização escolhido — ecoa o valor enviado.
`total_expected_amount`	number	Soma distribuída entre os `event_conciliation` (eventos de conciliação da parcela) pelo engine do tipo escolhido.
`total_discount_amount`	number	Desconto total aplicado. Diferente de zero apenas para `present_amount`.
`status`	string	Status inicial do evento extraordinário. Sempre `pending_conciliation` ao criar.
`reference_date`	string (date)	Data de referência enviada na requisição (deve corresponder a data de quitação).
`due_date`	string (date)	Data alvo de liquidação enviada na requisição.
`event_conciliation_list`	array	Lista de `event_conciliation` (evento de conciliação da parcela) gerado. Objeto event_conciliation_list.

Objeto event_conciliation_list

Campo	Tipo	Descrição
`event_conciliation_key`	string (UUID)	Chave do evento de conciliação da parcela (`event_conciliation`).
`installment_key`	string (UUID)	Chave da parcela afetada por este evento de conciliação.
`expected_amount`	number	Valor atribuído a este evento de conciliação da parcela pela engine de distribuição. Em `full_amortization`, é `0` na parcela com Valor Presente 0 quitada sem pagamento, que também tem `discount_amount` `0` — veja Regras de Negócio.
`discount_amount`	number	Parcela do `total_discount` alocada a este evento de conciliação da parcela (`present_amount`) ou diferença entre o Valor Presente da parcela e a cota recebida (`full_amortization`).
`due_date`	string (date)	Data de vencimento da parcela associada.
`status`	string	Status inicial do evento de conciliação da parcela. Sempre `pending_conciliation` ao criar.
`event_conciliation_type`	string	Tipo do `event_conciliation`. Sempre `extraordinary` para eventos de conciliação da parcela criados por este fluxo.

Erros

Código	HTTP	Significado
EVC100001	400	`amortization_type` inválido. Use um dos sete valores suportados.
EVC100002	400	`installment_list` é obrigatório (e não vazio) para todos os tipos de amortização.
EVC100003	400	`number_of_installments` é obrigatório para `first_installments`.
EVC100004	400	Alguma parcela informada não pertence à `security` alvo.
EVC000007	404	Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`).
QIT000001	400	Falha de schema — por exemplo, envio do legado `installment_key_list` (removido), item de `installment_list` que não é inteiro ≥ 1 ou número repetido em `installment_list`.
EVC100005	400	`amount` não cobre todas as parcelas selecionadas (não aplicável a `early_amortization`).
EVC100006	400	`total_discount` excede a soma do Valor Presente das parcelas selecionadas.
EVC100007	400	Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas.
EVC100008	400	Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de criar outra.
EVC100013	424	Security API indisponível (Failed Dependency). Transitório — repita após o restabelecimento.
EVC100015	400	`early_amortization` requer exatamente 1 parcela em `installment_list`.
EVC100016	400	A parcela alvo de `early_amortization` não pode estar vencida.
EVC100017	400	Em `early_amortization`, `amount` deve ser menor ou igual ao Valor Presente da parcela.
EVC100030	400	Em `nominal_amount`, todas as parcelas selecionadas devem ser futuras (não vencidas na `reference_date`).
EVC100031	400	Em `nominal_amount`, `amount` deve ser menor ou igual à soma dos valores nominais das parcelas selecionadas.
EVC100032	400	Nenhuma parcela selecionada receberia `expected_amount` positivo — o evento não é criado.
EVC100033	400	A soma dos `expected_amount` distribuídos difere do `amount` informado em mais de R$ 0,01.
EVC100034	400	Alguma parcela selecionada ficaria com `expected_amount` zero, inclusive após o arredondamento para centavos — selecione apenas parcelas que o `amount` cubra. Em `full_amortization`, também é retornado para parcela com Valor Presente 0 quando o ativo, o investidor ou a parcela não atendem às condições de quitação sem pagamento.
EVC100035	400	`amount` excede a soma dos Valores Presentes das parcelas selecionadas (tipos precificados a Valor Presente).
EVC100037	400	Em `full_amortization`, `installment_list` traz parcela com Valor Presente 0, mas não quita todo o principal em aberto. A mensagem lista as parcelas com principal que faltam.
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`. A mensagem lista as parcelas faltantes.

Consulte o Catálogo de erros para resolução completa.

Request​

Request Body​

Request Body Params​

Response​

Response Body Params​

Objeto event_conciliation_list​

Erros​

Veja também​