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

Existem dois modos de criação. Modo 1 — Targeted exige installment_list (array de installment_number, inteiros ≥ 1) e é usado com os tipos early_amortization, present_amount e matured_installments. Modo 2 — Acquittance não recebe installment_list e é usado com os tipos equal_amount e first_installments. Os números enviados em installment_list são resolvidos pelo serviço contra installment_number da security correspondente.

Exemplo — Modo 1 (early_amortization):

{
  "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 — Modo 2 (equal_amount):

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

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`.
`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)	Condicional	Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. Obrigatório para `present_amount`, `matured_installments` e `early_amortization`. Omita para `equal_amount` e `first_installments` para usar distribuição por acquittance (Modo 2). 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).
`total_discount`	number	Não	Utilizado apenas com `present_amount` — distribui o desconto na ordem juros → multa → principal.
`number_of_installments`	integer	Não	Utilizado apenas com `first_installments`, quando `installment_list` não é informado.

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.
`discount_amount`	number	Parcela do `total_discount` alocada a este evento de conciliação da parcela (quando aplicável).
`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 cinco valores suportados.
EVC100002	400	`installment_list` é obrigatório (e não vazio) para `present_amount`, `matured_installments` ou `early_amortization`.
EVC100003	400	`number_of_installments` é obrigatório para `first_installments` quando `installment_list` não é enviado.
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) ou item de `installment_list` que não é inteiro ≥ 1.
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.

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​