Recálculo e Retentativa de Averbação

Fluxo de recálculo da compra de dívida do consignado militar. Quando o Exército recusa a averbação — margem insuficiente, prazo acima do permitido, consignação indeferida — a operação já assinada não precisa ser cancelada: o parceiro recalcula as condições a partir de um novo valor de parcela e reenvia a averbação, na mesma CCB e no mesmo lote.

O recálculo também é o passo que dimensiona o refinancing consolidador depois que as portabilidades do lote são averbadas — nesse caso não há recusa nenhuma envolvida, apenas o ajuste do valor final da operação mãe.

São duas rotas, usadas em conjunto:

ENDPOINT

/v2/credit_operation/CREDIT_OPERATION_KEY/recalculate

MÉTODO

PATCH

ENDPOINT

/debt/CREDIT_OPERATION_KEY/reservation/retry

MÉTODO

PATCH

Divisão de responsabilidade entre as duas rotas

recalculate reescreve as condições financeiras da CCB e propaga essas condições para a averbação. Não é necessária nenhuma chamada adicional para atualizar a reserva — mas o reservation_status não muda.
reservation/retry é o que devolve uma averbação recusada (pending_requester_action) para a fila de envio (pending_reservation), de onde a QI Tech a reenvia ao Exército.

Uma averbação recusada só volta a ser tentada com o reservation/retry. Um recálculo feito antes do envio da averbação (caso do consolidador em created / pending_reservation) não exige retry — a averbação segue o fluxo normal já com as condições novas.

Quando usar

Situação	O que fazer
Webhook `credit_operation.collateral` com `reservation_status: pending_requester_action` na portabilidade	Recalcular a portabilidade com parcela que caiba na margem informada e retentar
Todas as portabilidades do lote averbadas (`reserved`)	Recalcular o `refinancing` consolidador para o valor definitivo
Webhook `credit_operation.collateral` com `reservation_status: pending_requester_action` no consolidador	Recalcular o consolidador e retentar
Averbação parada por token inválido (`pending_valid_token`)	Não é recálculo — atualizar o token do militar
Falha de comunicação com o Exército	Nada a fazer — a QI Tech retenta automaticamente
Garantia já constituída (`reserved`)	Nada a fazer — o recálculo é recusado com `COP000556`
Condições novas fora do que a operação suporta	Cancelar e reemitir o lote (ver Cancelamento)

Por que a averbação para

Recusas que nenhuma retentativa automática resolve deixam a averbação parada em pending_requester_action, aguardando condições novas do parceiro, em vez de cancelar a operação. O aviso chega pelo webhook credit_operation.collateral (ver Webhooks):

{
  "webhook_type": "credit_operation.collateral",
  "key": "8916175e-18df-4845-a238-643f52b77be4",
  "data": {
    "collateral_type": "military_payroll",
    "collateral_constituted": false,
    "operation_type": "portability_for_refinancing",
    "collateral_data": {
      "reservation_status": "pending_requester_action",
      "cancel_reason": "consignable_margin_exceeded"
    }
  },
  "event_datetime": "2026-09-08 14:30:00"
}

Recusas na inclusão da consignação

`cancel_reason`	Código Zetra	Significado
`consignable_margin_exceeded`	359	Margem consignável excedida
`period_quantity_exceeded`	347	Quantidade de parcelas acima do permitido
`military_payroll_period_quantity_exceeded`	471	Quantidade de parcelas acima do permitido na verba
`military_blocked`	352	Militar com bloqueio em folha
`military_not_found`	293	Militar não localizado com CPF/matrícula informados
`portability_not_found`	294	Contrato de origem não localizado para portabilidade

Recusas na confirmação da averbação

`cancel_reason`	Situação no Exército	Significado
`rejected`	`Indeferida`	Averbação indeferida
`suspended`	`Suspensa`	Consignação suspensa
`suspend_by_manager`	`Suspensa Pelo Gestor`	Consignação suspensa pelo gestor
`closed_by_exclusion`	`Encerrado por Exclusão`	Consignação encerrada por exclusão

Nem toda parada é recálculo

pending_valid_token (token do militar inválido ou ausente) e falhas de comunicação não entram nesse fluxo: a primeira se resolve com a atualização do token, a segunda é retentada automaticamente pela QI Tech.

Ciclo completo do lote

O lote é recalculado em duas rodadas, com a resposta do Exército no meio: primeiro as portabilidades, depois o refinanciamento consolidador.

1.  PATCH /v2/credit_operation/{portability}/recalculate     nova parcela da portabilidade
        ↓
2.  PATCH /debt/{portability}/reservation/retry              204 — volta para pending_reservation
        ↓
3.  [ Exército responde a averbação reenviada ]
        ├── reserved                 → repita 1 e 2 nas demais portabilidades, depois siga para 4
        └── pending_requester_action → volta ao passo 1 com parcela menor
        ↓
4.  PATCH /v2/credit_operation/{refinancing}/recalculate     parcela definitiva do consolidador
        ↓
5.  PATCH /debt/{refinancing}/reservation/retry              204 (só se o consolidador estiver parado)
        ↓
6.  [ Exército averba o consolidador ]                       → operação segue para desembolso

Ordem obrigatória

As portabilidades são recalculadas e averbadas antes do consolidador. O recálculo do refinancing é recusado com MPR000037 enquanto qualquer portabilidade do lote não estiver em reserved — é o valor averbado das portabilidades que dimensiona o consolidador.

Num lote do cenário β (N portabilidades), todas passam pelos passos 1 a 3 antes do passo 4.

1. Recalcular a portabilidade

Recalcula as condições financeiras da portabilidade a partir do novo valor de parcela. O valor líquido é travado: a portabilidade tem de quitar exatamente o saldo devedor do contrato de origem, então quem cede é a taxa — parcela menor ⇒ taxa menor, parcela maior ⇒ taxa maior.

ENDPOINT

/v2/credit_operation/CREDIT_OPERATION_KEY/recalculate

MÉTODO

PATCH

Path Params

credit_operation_key string (UUID) obrigatório Chave da portabilidade — a key retornada pelo POST /debt do Passo 5 de Portabilidade + Refinanciamento.

Body Params

installment_amountnumberobrigatórioNovo valor total da parcela, maior que 0 e com no máximo 2 casas decimais. É o valor que toda parcela do fluxo vai passar a ter.

{
  "installment_amount": 95.00
}

installment_amount é o único campo aceito

Qualquer outra condição (monthly_interest_rate, number_of_installments, final_disbursement_amount) é recusada com COP000557. Campo desconhecido, corpo vazio, valor não numérico ou installmentAmount em camelCase são recusados com QIT000001; três casas decimais, com COP000564.

Pré-condições

Só é recalculável a operação que:

Condição	Erro quando não atendida
Tem garantia `military_payroll`	`COP000553`
Tem tipo de reserva `portability` ou `refinancing` na garantia	`COP000554` / `COP000568`
Está assinada e emitida (status `issued`)	`COP000555`
Ainda não teve a garantia constituída	`COP000556`
Tem contrato de origem com saldo devedor	`COP000566`
Tem opção de desembolso em ou após hoje	`COP000559`
Não tem parcela com valor pago	`COP000561`
Não tem entrada emitida	`COP000562`
Tem a averbação parada em `pending_requester_action`	`MPR000009`

A averbação só existe depois da assinatura

A averbação é solicitada depois do signature_finished, não no POST /debt. Antes disso o recálculo responde MPR000017 (não há averbação para a operação). Com a averbação já solicitada mas ainda em pending_reservation ou pending_confirmation, responde MPR000009, e a descrição do erro traz o status atual — é assim que se confere em que ponto a averbação está, além do webhook credit_operation.collateral e do GET /debt/{DEBT_KEY}/collateral.

Response

STATUS

200

Devolve a operação recalculada inteira, com as parcelas reescritas. Campos relevantes:

Response Body

{
  "credit_operation_key": "8916175e-18df-4845-a238-643f52b77be4",
  "credit_operation_status": "issued",
  "operation_type": "portability_for_refinancing",
  "collateral_type": "military_payroll",
  "collateral_constituted": false,
  "disbursement_date": "2026-09-16",
  "number_of_installments": 20,
  "issue_amount": 1686.84,
  "disbursed_issue_amount": 1680.84,
  "final_disbursement_amount": 0,
  "base_iof": 5.98,
  "additional_iof": 0.02,
  "total_iof": 6.00,
  "annual_cet": 0.1495,
  "interest_type": "pre_price_days",
  "prefixed_interest_rate": {
    "interest_base": "calendar_days",
    "daily_rate": 0.00035739,
    "monthly_rate": 0.01079689,
    "annual_rate": 0.13756
  },
  "installments": [
    {
      "installment_key": "1b6a2c58-0f37-4f21-9c2e-2a7f0c1d4e55",
      "installment_number": 1,
      "due_date": "2026-10-16",
      "total_amount": 95.00,
      "principal_amortization_amount": 76.79,
      "pre_fixed_amount": 18.21,
      "installment_status": "opened"
    },
    { "...": "parcelas 2 a 20" }
  ],
  "disbursement_options": [
    { "...": "mesma estrutura, uma entrada por data de desembolso disponível" }
  ]
}

Opções de desembolso

Havendo várias opções de desembolso, o recálculo reescreve todas as que ainda estão dentro da janela (data em ou após hoje) e aplica na operação a que corresponde à disbursement_date vigente. Opções com data passada são preservadas como estão. Leia sempre a opção cuja disbursement_date é a da operação.

O que muda e o que fica travado

Campo	Comportamento na portabilidade
`installments[].total_amount`	Todas as parcelas passam a valer exatamente o `installment_amount` enviado
`disbursed_issue_amount`	Travado — igual ao saldo devedor do contrato de origem
`issue_amount`	Recalculado — igual ao valor líquido somado ao IOF
`prefixed_interest_rate.*`	Recalculada. Parcela menor ⇒ taxa menor; `daily` < `monthly` < `annual`
`number_of_installments`	Travado
`installments[].due_date` / `installment_key`	Preservados — as parcelas são reescritas, não recriadas
`final_disbursement_amount`	`0` na portabilidade (sem troco)
`additional_iof`	Cobrado somente sobre dinheiro novo (`issue_amount` menos o saldo devedor portado)
Σ `principal_amortization_amount`	Igual ao `issue_amount`
Componentes da parcela	`principal_amortization_amount` + `pre_fixed_amount` = `total_amount`

Como conferir a resposta

Em interest_type: pre_price_days, o valor presente das parcelas descontado pela daily_rate por dias corridos reconstitui o issue_amount:

Σ total_amount / (1 + daily_rate) ^ (due_date − disbursement_date) == issue_amount

Recálculo é tudo-ou-nada

Se o resultado do cálculo violar qualquer uma das travas da tabela acima, a resposta é COP000560, com o nome da invariante violada, o valor esperado e o obtido na descrição. Se a averbação recusar as condições novas (por exemplo, MPR000036), a resposta é o próprio erro da averbação.

Nos dois casos nada é gravado: a operação continua com as condições da emissão e a averbação, com as condições anteriores. Basta corrigir o installment_amount e chamar de novo.

2. Retentar a averbação da portabilidade

Devolve a averbação de pending_requester_action para pending_reservation, já com as condições gravadas pelo recálculo. A QI Tech a reenvia ao Exército na varredura seguinte.

ENDPOINT

/debt/CREDIT_OPERATION_KEY/reservation/retry

MÉTODO

PATCH

Body Params

A rota não aceita nenhum campo. Qualquer propriedade enviada é recusada com QIT000001 — inclusive token, que tem rota própria.

{}

O corpo vazio é {}, não ausente

A rota não tem campo obrigatório, mas a requisição sem corpo é recusada com GDF000028. Envie {} — e calcule a assinatura sobre a string {}, não sobre a string vazia.

Response

STATUS

204

204 sem corpo é o sucesso: a averbação voltou para pending_reservation. A rota apenas reposiciona a averbação na fila — o resultado do reenvio chega por webhook.

Erros possíveis

HTTP	Código	Quando
400	`QIT000001`	Corpo com qualquer campo
403	`QIT000003`	Requisitante da chamada não identificado
404	`GDF000028`	Requisição sem corpo — envie `{}`
404	`MPR000017`	Não há averbação para essa operação, ou ela pertence a outro requisitante
409	`MPR000009`	Averbação fora de `pending_requester_action` — o retry só vale para a averbação parada aguardando o requisitante

3. Averbado com sucesso, ou novo recálculo

O resultado do reenvio chega pelo webhook credit_operation.collateral:

`reservation_status`	`collateral_constituted`	O que fazer
`reserved`	`true`	Averbado. Portabilidade fechada — repita nas demais portabilidades e siga para o passo 4
`pending_confirmation`	`false`	Exército aceitou a inclusão, aguardando confirmação da averbação — espere o próximo evento
`pending_requester_action`	`false`	Recusado de novo. Repita os passos 1 e 2 com parcela menor (ver `cancel_reason`)
`pending_valid_token`	`false`	Token do militar inválido — atualizar o token; não é caso de recálculo

O ciclo recálculo → retry pode ser repetido quantas vezes a margem exigir. Cada iteração parte do estado atual da operação: o valor líquido continua travado no saldo devedor do contrato de origem, só a taxa acompanha a parcela.

Um recálculo por ciclo de averbação

Faça um recalculate, então o reservation/retry, e espere a resposta do Exército antes de recalcular de novo. Recalcular duas vezes seguidas, sem o retry no meio, sobrescreve as condições que ainda não foram enviadas.

Consulta de status

Além do webhook, o estado atual da averbação pode ser lido em GET /debt/{DEBT_KEY}/collateral (last_response + reservation_status). Respeite um intervalo de no mínimo 25 segundos entre consultas — a atualização do estado é assíncrona e leituras mais frequentes não refletem mudança.

4. Recalcular o refinanciamento consolidador

Com todas as portabilidades do lote averbadas, recalcule o refinancing consolidador — a CCB mãe que carrega seguro e troco. Mesma rota, mesmo corpo, com duas diferenças de comportamento.

ENDPOINT

/v2/credit_operation/CREDIT_OPERATION_KEY/recalculate

MÉTODO

PATCH

{
  "installment_amount": 9500.00
}

Use a key do refinancing retornada no Passo 6 de Portabilidade + Refinanciamento.

Diferenças em relação à portabilidade

Comportamento	Portabilidade	Refinanciamento consolidador
Taxa (`prefixed_interest_rate`)	Recalculada, acompanha a parcela	Preservada — a da emissão
`issue_amount` / `disbursed_issue_amount`	Líquido travado no saldo devedor	Acompanham a parcela — parcela menor ⇒ emissão menor
`final_disbursement_amount`	Sempre `0`	≠ 0 — é o troco, recalculado junto com a parcela
IOF	Só sobre dinheiro novo	Idem — sobre o `issue_amount` líquido do saldo portado
Averbação exigida em `pending_requester_action`	Sim	Não — aceita também `created` e `pending_reservation`
Portabilidades do lote averbadas	Não se aplica	Obrigatório — todas em `reserved` (`MPR000037`)

Por que o consolidador aceita recálculo sem recusa

O valor do consolidador só fica conhecido depois que as portabilidades de origem são averbadas. Por isso o recálculo do refinancing é aceito nos estados created, pending_reservation e pending_requester_action — nos dois primeiros é o ajuste normal do lote, sem retry: a averbação é enviada já com as condições novas.

Response Body

{
  "credit_operation_key": "50b950be-e7ec-484c-8c59-e7a1bbae020b",
  "credit_operation_status": "issued",
  "operation_type": "refinancing",
  "collateral_type": "military_payroll",
  "collateral_constituted": false,
  "disbursement_date": "2026-09-16",
  "number_of_installments": 20,
  "issue_amount": 157000.00,
  "disbursed_issue_amount": 155000.00,
  "final_disbursement_amount": 55000.00,
  "base_iof": 1783.40,
  "additional_iof": 216.60,
  "total_iof": 2000.00,
  "prefixed_interest_rate": {
    "interest_base": "calendar_days",
    "daily_rate": 0.00056214,
    "monthly_rate": 0.01700000,
    "annual_rate": 0.22421
  },
  "installments": [
    {
      "installment_key": "7c3d9e11-52a8-4b0e-9f41-b0a6d2c9e733",
      "installment_number": 1,
      "due_date": "2026-10-16",
      "total_amount": 9500.00,
      "principal_amortization_amount": 6832.14,
      "pre_fixed_amount": 2667.86,
      "installment_status": "opened"
    },
    { "...": "parcelas 2 a 20" }
  ]
}

Limite de redução do valor líquido

O valor líquido do consolidador não pode cair mais de 15% em relação ao valor da emissão original. Parcela que produza um líquido abaixo desse piso é recusada com MPR000036, e a descrição do erro traz o valor original, o novo e o mínimo permitido. Aumento não tem teto.

Reduções maiores que 15% exigem cancelamento e reemissão do lote (ver Cancelamento).

As demais pré-condições, travas de resposta e códigos de erro são os do passo 1.

5. Retentar a averbação do refinanciamento

Necessário apenas se a averbação do consolidador estiver parada em pending_requester_action. Nos estados created e pending_reservation a averbação segue sozinha com as condições novas.

ENDPOINT

/debt/CREDIT_OPERATION_KEY/reservation/retry

MÉTODO

PATCH

Corpo {} · Resposta 204. Comportamento e erros idênticos ao passo 2.

6. Refinanciamento averbado

Webhook credit_operation.collateral com reservation_status: reserved e collateral_constituted: true no consolidador fecha o ciclo: com a garantia constituída, a operação segue para o desembolso normal (waiting_disbursement → disbursed), conforme Mapa de Status.

A partir daí a operação não é mais recalculável — recalculate passa a responder COP000556 (garantia já constituída).

Erros possíveis no recálculo

HTTP	Código	Quando
400	`QIT000001`	Corpo fora do schema — vazio, campo desconhecido, tipo errado
403	`QIT000403`	Requisitante da chamada não identificado
403	`QIT000005`	Requisitante não é dono da operação
404	`COP000027`	`credit_operation_key` não encontrada
400	`COP000553`	Tipo de garantia não recalculável
400	`COP000554`	Operação sem tipo de reserva na garantia
400	`COP000568`	Tipo de reserva sem recálculo disponível (ex.: `new_credit`, margem livre)
400	`COP000555`	Status ≠ `issued` — a operação ainda não foi assinada e emitida
400	`COP000556`	Garantia já constituída — a averbação passou, não há o que recalcular
400	`COP000557`	Condição não aceita — só `installment_amount`
400	`COP000558`	`installment_amount` ausente
400	`COP000559`	Nenhuma opção de desembolso em ou após hoje
400	`COP000560`	O resultado do cálculo violou uma trava da operação — nada é gravado
400	`COP000561`	Existe parcela com valor pago
400	`COP000562`	Operação com entrada emitida
400	`COP000564`	Condição com mais de 2 casas decimais
400	`COP000566`	Sem contrato portado/refinanciado com saldo devedor
400	`COP000567`	Operação sem taxa pré-fixada de referência
400	`COP000339`	Parcela insuficiente para o valor da operação — resultaria em troco negativo
400	`MPR000036`	Valor líquido abaixo de 85% do valor da emissão original
404	`MPR000017`	Não há averbação para essa operação
409	`MPR000009`	Averbação em status que não permite recálculo — a descrição traz o status atual
409	`MPR000037`	Consolidador com portabilidade do lote fora de `reserved`

Simulação em Sandbox

Os cenários de recusa são selecionados pelos dois últimos dígitos do CPF do tomador (são os dígitos verificadores — escolha uma base de 9 dígitos cujos verificadores resultem no sufixo desejado):

Sufixo do CPF	Cenário	Onde para
`40`	Inclusão recusada com código 359 (margem consignável excedida)	`pending_requester_action` com `cancel_reason: consignable_margin_exceeded`
`41`	Averbação indeferida na confirmação (`Indeferida`)	`pending_requester_action` com `cancel_reason: rejected`

Roteiro de teste:

Emita e assine o lote com um CPF de cenário (ver Portabilidade + Refinanciamento e Formalização).
Aguarde o webhook credit_operation.collateral com reservation_status: pending_requester_action.
PATCH /v2/credit_operation/{portability}/recalculate com a parcela nova → 200.
PATCH /debt/{portability}/reservation/retry → 204.

O cenário de recusa não "cura" em sandbox

O CPF de cenário recusa toda tentativa de inclusão ou averbação. Para exercitar o caminho completo até reserved, use no reenvio um tomador sem sufixo de cenário. Ver Mocks (Sandbox) para os demais dados de teste.

Resumo do ciclo

Passo	Chamada	Sucesso	Próximo gatilho
1	`PATCH /v2/credit_operation/{portability}/recalculate`	200 com parcelas reescritas	—
2	`PATCH /debt/{portability}/reservation/retry`	204	Webhook `credit_operation.collateral`
3	—	`reserved` → passo 4	Recusa → volta ao passo 1
4	`PATCH /v2/credit_operation/{refinancing}/recalculate`	200 (troco ≠ 0)	—
5	`PATCH /debt/{refinancing}/reservation/retry`	204 (só se parado)	Webhook `credit_operation.collateral`
6	—	`reserved` + `collateral_constituted: true`	Desembolso

Glossário

Termo	Significado
`installment_amount`	Novo valor total da parcela enviado ao recálculo — único campo aceito
`pending_requester_action`	Averbação recusada por motivo que exige condições novas do parceiro. Único estado em que o recálculo da portabilidade é aceito, e único em que o retry funciona
`pending_reservation`	Averbação aguardando envio ao Exército — onde o `reservation/retry` a coloca
`pending_confirmation`	Inclusão aceita, aguardando a confirmação da averbação
`pending_valid_token`	Averbação parada por token do militar inválido — resolve-se pela atualização do token, não por recálculo
`reserved`	Margem averbada, garantia constituída — a operação deixa de ser recalculável
valor líquido	`disbursed_issue_amount` — travado no saldo devedor portado na portabilidade; acompanha a parcela no consolidador
troco	`final_disbursement_amount` — só existe no `refinancing` consolidador; na portabilidade é sempre `0`

Quando usar​

Por que a averbação para​

Recusas na inclusão da consignação​

Recusas na confirmação da averbação​

Ciclo completo do lote​

1. Recalcular a portabilidade​

Path Params​

Body Params​

Pré-condições​

Response​

O que muda e o que fica travado​

Recálculo é tudo-ou-nada​

2. Retentar a averbação da portabilidade​

Body Params​

Response​

Erros possíveis​

3. Averbado com sucesso, ou novo recálculo​

4. Recalcular o refinanciamento consolidador​

Diferenças em relação à portabilidade​

Limite de redução do valor líquido​

5. Retentar a averbação do refinanciamento​

6. Refinanciamento averbado​

Erros possíveis no recálculo​

Simulação em Sandbox​

Resumo do ciclo​

Glossário​

Quando usar

Por que a averbação para

Recusas na inclusão da consignação

Recusas na confirmação da averbação

Ciclo completo do lote

1. Recalcular a portabilidade

Path Params

Body Params

Pré-condições

Response

O que muda e o que fica travado

Recálculo é tudo-ou-nada

2. Retentar a averbação da portabilidade

Body Params

Response

Erros possíveis

3. Averbado com sucesso, ou novo recálculo

4. Recalcular o refinanciamento consolidador

Diferenças em relação à portabilidade

Limite de redução do valor líquido

5. Retentar a averbação do refinanciamento

6. Refinanciamento averbado

Erros possíveis no recálculo

Simulação em Sandbox

Resumo do ciclo

Glossário