Cancelamento, Desaverbação e Reversal

Cancelar uma operação militar tem dois eixos independentes:

1. Cancelamento da CCB — estado da operação no LaaS, e eventual estorno do dinheiro desembolsado.
2. Desaverbação no Zetra — liberação da margem em folha de pagamento.

Os dois acontecem de forma assíncrona e nem sempre simultâneos. Cancelar a operação NÃO libera a margem instantaneamente; pagar de volta o dinheiro desembolsado também é um passo separado.

1. Pré-desembolso — Cancelamento Imediato

Antes do desembolso (operação em waiting_signature, signature_finished ou waiting_disbursement):

PATCH /debt/{DEBT_KEY}/cancel

Sem body. Resposta imediata: operação vai pra canceled. Não há reversal financeiro (dinheiro nem saiu).

Webhook: debt com status: canceled + cancel_reason_enumerator indicando o motivo (manual, waiting_signature, not_collateral_constituted, etc.).

A QI dispara em seguida a desaverbação no Zetra (ver seção 4).

2. Pós-desembolso — Janela de Desistência (7 dias úteis)

A janela legal de desistência é de 7 dias úteis após o desembolso. Dentro dela:

PATCH /debt/{DEBT_KEY}/cancel

A response NÃO é instantânea como o pré-desembolso — retorna um PIX QR Code que o borrower deve pagar pra devolver o dinheiro desembolsado. O parceiro repassa o QR pro cliente.

Campo na response	Significado
cancel_qr_code.qr_code_url / digitable_line	PIX copia-e-cola ou QR pra pagamento
cancel_qr_code.amount	Valor a devolver (igual ao desembolsado)
cancel_qr_code.expiration	Prazo pro pagamento (15 dias úteis após desembolso)

Quando o borrower paga o PIX:

1. QI confirma o pagamento.
2. Dispara o reversal financeiro automático — desfaz o desembolso, devolve pro fundo.
3. Webhook reversal chega:

   {
     "webhook_type": "reversal",
     "credit_operation_key": "<uuid>",
     "contract_number": "<...>",
     "reversal": {
       "status": "pending_fund",
       "amount": 2026.93,
       "amount_to_send": 2026.93,
       "is_total": true,
       "is_operation_canceled": true,
       "reversal_key": "<uuid>",
       "date": "2026-09-06"
     }
   }

4. QI dispara a desaverbação no Zetra.
5. Operação vai pra canceled.

[!warning] Prazo de pagamento do QR O QR tem validade de 15 dias úteis após o desembolso (não após emissão do QR). Se o borrower não pagar dentro desse prazo, o cancelamento expira e a operação volta a ser ativa — vira inadimplência normal (cobrança de parcelas segue o curso).

Restrições pós-desembolso:

• Operação precisa estar em status open (sem parcelas pagas).
• Pagamento parcial de qualquer parcela bloqueia o cancelamento.
• Não há cancelamento parcial — só total.

3. Cancelamento Permanente

PATCH /debt/{DEBT_KEY}/cancel/permanent

Marca como canceled_permanently — não há volta. Útil pra:

• Cliente desistiu e não vai pagar o QR (vira inadimplência → permanent depois)
• Operação que ficou pendente além do prazo (auto-cancel já faz isso em 7 dias, mas pode forçar)

Sem reversal automático — usar apenas se o dinheiro já foi resolvido por fora ou nunca saiu.

4. Desaverbação no Zetra

Independente do cancelamento financeiro, a desaverbação é processada pelo Zetra de forma assíncrona:

Status no credit_operation.collateral	Significado
waiting_confirmation	Zetra ainda processando a desaverbação
successfully_deleted	Margem liberada
communication_error	Zetra indisponível (cod 241) — QI retenta automaticamente

[!warning] Não considere a margem liberada até successfully_deleted chegar. Emitir nova operação no mesmo militar antes da desaverbação confirmada retorna consignable_margin_exceeded.

Pra consultar o estado:

GET /debt/{DEBT_KEY}/collateral

Retorna last_response + reservation_status atual.

5. Auto-cancelamento (7 dias)

Operações em status canceled (não-permanente) por mais de 7 dias são automaticamente convertidas em canceled_permanently pelo sistema. Aplica-se a:

• Operação cuja averbação foi recusada (consent_refused)
• Operação cuja averbação expirou (consent_expired)
• Operação pendente de assinatura além do prazo
• Operação com cancelamento solicitado mas QR não pago dentro de 15 dias úteis

Não precisa fazer nada — o sistema cancela e desaverba sozinho.

Resumo dos Endpoints

Endpoint	Quando usar	Reversal automático?
PATCH /debt/{KEY}/cancel (pré-desembolso)	Antes do desembolso	Não aplica (dinheiro não saiu)
PATCH /debt/{KEY}/cancel (pós-desembolso)	Dentro de 7 dias úteis após desembolso	Sim — após borrower pagar o PIX QR retornado
PATCH /debt/{KEY}/cancel/permanent	Cancelamento definitivo (sem volta)	Não — uso administrativo

Cancel reasons no webhook debt (status: canceled)

Os principais cancel_reason_enumerator que aparecem:

Enumerador	Significado
manual	Cancelado via API ou portal
waiting_signature	Não assinou no prazo
not_collateral_constituted	Averbação falhou
is_portability	Portabilidade falhou
pix_max_retry	Muitas falhas no desembolso PIX
lack_of_resource	Sem recurso pra desembolsar
kyc_not_accepted	KYC reprovado

→ Lista completa de enumeradores em Mapa de Status