Cancelamento, Desaverbação e Reversal (SIAPE)

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

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

Os dois acontecem de forma assíncrona. Cancelar a operação NÃO libera a margem instantaneamente.

1. Pré-desembolso — Cancelamento Imediato

PATCH /debt/{DEBT_KEY}/cancel

Operação imediatamente vai pra canceled. Sem reversal financeiro (dinheiro nem saiu). QI dispara em seguida a desaverbação no SIGEPE.

Webhook: debt com status: canceled + cancel_reason_enumerator.

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

Janela legal de 7 dias úteis após desembolso. Dentro dela:

PATCH /debt/{DEBT_KEY}/cancel

A response retorna um PIX QR Code pra borrower pagar de volta o dinheiro desembolsado:

Campo na response	Significado
cancel_qr_code.qr_code_url / digitable_line	PIX copia-e-cola
cancel_qr_code.amount	Valor a devolver
cancel_qr_code.expiration	Prazo (15 dias úteis após desembolso)

Quando o borrower paga:

1. QI confirma o pagamento.
2. Dispara o reversal financeiro automático.
3. Webhook reversal:

   {
     "webhook_type": "reversal",
     "credit_operation_key": "<uuid>",
     "reversal": {
       "status": "pending_fund",
       "amount": 2026.93,
       "is_total": true,
       "is_operation_canceled": true,
       "reversal_key": "<uuid>"
     }
   }

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

[!warning] Janela operacional do SIGEPE afeta desaverbação Como o SIAPE só processa 07:00-00:00 em dias úteis, a desaverbação pode demorar. Cancelamento de PIX QR funciona 24/7 (BaaS); só a parte do SIGEPE espera janela.

Restrições pós-desembolso:

• Status open (sem parcelas pagas).
• Pagamento parcial bloqueia o cancelamento.
• Sem cancelamento parcial.

3. Cancelamento Permanente

PATCH /debt/{DEBT_KEY}/cancel/permanent

canceled_permanently — não há volta. Sem reversal automático.

4. Desaverbação no SIGEPE

Status	Significado
waiting_confirmation	SIGEPE ainda processando
successfully_deleted	Margem liberada
communication_error	SIGEPE indisponível — QI retenta

Pra consultar:

GET /debt/{DEBT_KEY}/collateral

5. Auto-cancelamento (7 dias)

Operações em canceled por mais de 7 dias viram automaticamente canceled_permanently. Aplica-se a:

• consent_refused
• consent_expired
• Pendente de assinatura além do prazo
• QR não pago dentro de 15 dias úteis

Resumo dos Endpoints

Endpoint	Quando usar	Reversal automático?
PATCH /debt/{KEY}/cancel (pré-desembolso)	Antes do desembolso	Não aplica
PATCH /debt/{KEY}/cancel (pós-desembolso)	Em até 7 dias úteis após desembolso	Sim — após borrower pagar o PIX QR
PATCH /debt/{KEY}/cancel/permanent	Definitivo (sem volta)	Não

Cancel reasons no webhook debt (status: canceled)

Enumerador	Significado
manual	Cancelado via API ou portal
waiting_signature	Não assinou no prazo
not_collateral_constituted	Averbação falhou (consent_refused, consent_expired, etc.)
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