Esta rota realiza a solicitação de cancelamento de um protesto a partir do identificador do título e tipo do cancelamento.

Requisição

*TituloId ou ProtestoId deve ser informado. Se TituloId = 0, ProtestoId é obrigatório.

Enum TipoCancelamento

Resposta

Fluxos de Cancelamento

1. CANCELAMENTO_ENVIO (Tipo = 1)

• Quando usar: Apenas quando situação = AGUARDANDO_COLETA (título ainda não foi enviado ao cartório)
• Sucesso (HTTP 2xx): Cancelamento instantâneo. Estado muda para INSERIDO imediatamente. Não aguarda webhook.
• Erro HTTP 422 CANCELAMENTO_ENVIO_INVALIDO: Título já foi enviado ao cartório. Não é erro técnico, é fluxo inválido. Retorna erro sem alterar estado. Aguarde título chegar em COLETADO ou NO_CARTORIO e use outro fluxo.

2. AUTORIZACAO (Tipo = 0)

• Quando usar: Apenas quando situação = PROTESTADO ou PROTESTO_POR_EDITAL
• Sucesso (HTTP 2xx): Estado muda para CANCELAMENTO_SOLICITADO. Email/SMS é enviado ao devedor informando que deve pagar custas no cartório.
• Próximos passos: Aguarda webhook SITUACAO_TITULO com situacao = RETIRADO ou PROTESTO_CANCELADO para finalizar como CANCELADO.
• Observação: Job de sincronização não marca erro se situação continuar PROTESTADO/NO_CARTORIO/COLETADO após solicitar autorização.

3. PEDIDO_CANCELAMENTO (Tipo = 2) - Pagamento Antecipado

• Quando usar: Quando o credor quer pagar as custas antecipadamente via Pix. Pode ser feito em qualquer situação após protesto efetivado.
• Sucesso (HTTP 2xx): Estado muda para CANCELAMENTO_SOLICITADO.
• Próximos passos:
  1. Aguarda webhook VALOR_CANCELAMENTO (com valor, QR Code PIX e prazo). Estado muda para VALOR_CANCELAMENTO.
  2. Cliente paga via PIX.
  3. Aguarda webhook SITUACAO_TITULO com situacao = RETIRADO ou PROTESTO_CANCELADO. Estado final muda para CANCELADO.
• Observação: Job de sincronização não marca erro quando cancelamento_solicitado = true e situação é COLETADO, NO_CARTORIO, etc. Esses são estados normais do fluxo durante cancelamento.

Webhooks Recebidos

Webhook VALOR_CANCELAMENTO (apenas para PEDIDO_CANCELAMENTO)

{
  "titulo_id": 17509,
  "tipo": "VALOR_CANCELAMENTO",
  "prazo_cancelamento": "19/07/2021 15:00:00",
  "valor": "100.00",
  "codigo_pix": "00020126360014BR.GOV.BCB.PIX2567..."
}

• Estado muda para VALOR_CANCELAMENTO
• Cliente recebe notificação com valor, QR Code PIX e prazo

Webhook SITUACAO_TITULO (finalização)

{
  "titulo_id": 17509,
  "tipo": "SITUACAO_TITULO",
  "situacao": "RETIRADO" // ou "PROTESTO_CANCELADO"
}

• Estado final muda para CANCELADO (não RETIRADO ou PROTESTO_CANCELADO)
• Aplica-se tanto para AUTORIZACAO quanto para PEDIDO_CANCELAMENTO

Códigos de Resposta HTTP

Observações Importantes

• No primeiro momento, quando o cancelamento é solicitado, pode não existir um título criado ainda, apenas o protesto.
  Neste caso, TituloId será 0 e ProtestoId estará preenchido.
• O retorno "CREATED" indica que a solicitação de cancelamento foi criada com sucesso.
• Para PEDIDO_CANCELAMENTO e AUTORIZACAO, o cancelamento não é instantâneo. O estado final (CANCELADO) só é definido via webhook SITUACAO_TITULO.
• O job de sincronização (executado a cada 5 minutos) não marca erro quando cancelamento_solicitado = true, mesmo que a situação seja COLETADO, NO_CARTORIO, etc.