Fluxos - Cancelar uma Reserva que Já Tem Pagamento

O que é

Este fluxo cobre o caso em que o cliente desiste de uma reserva que já tem pelo menos um pagamento registrado - seja uma parcela agendada, um PIX recebido ou um pagamento via meio de pagamento. Diferente do cancelamento "limpo" (sem dinheiro envolvido), aqui o atendente precisa decidir, em sequência, três coisas:

1. Cancelar a reserva no Viagilize (libera vaga, ajusta financeiro do grupo, encerra alocação de quarto).
2. Definir o que acontece com o dinheiro já recebido: estorno integral, estorno parcial (retendo multa), ou conversão em crédito futuro.
3. Executar a devolução em si - que, para pagamentos via meio de pagamento, acontece fora do Viagilize, no painel do meio de pagamento que processou a cobrança.

O Viagilize não dispara estorno automático no meio de pagamento ao cancelar. O cancelamento marca o financeiro como cancelado e libera a vaga; a devolução do dinheiro é uma operação manual subsequente.

Como usar

Passo 1 - Levantar a situação financeira antes de cancelar

1. Vá em Reservas no sidebar e abra a reserva em /admin/reservas/{passageiro}.
2. No card Financeiro da coluna direita, anote: Valor Total, Valor Pago, Valor Pendente e o status atual (Pendente, Parcial, Pago, Reembolsado).
3. Desça até a seção Plano de Pagamentos e identifique para cada pagamento:
   • Status: Pendente, Aguardando Confirmação, Confirmado ou Cancelado.
   • Origem: manual (PIX direto, dinheiro, transferência, boleto interno, cheque) ou meio de pagamento (Mercado Pago, Asaas, Pagar.me, InfinitePay).
   • Estornado: se já tem etiqueta de estorno parcial/total.
4. Combine com o cliente a forma da devolução (PIX para a mesma chave, crédito para próxima viagem, retenção de multa). Registre o acordo por escrito (WhatsApp, e-mail) antes de seguir.

Passo 2 - Cancelar a reserva

1. No topo da tela de detalhes, clique no botão Ações e selecione Cancelar Reserva (opção em vermelho).
2. No modal Cancelar Reserva, preencha Motivo do Cancelamento (obrigatório, até 500 caracteres). Inclua a decisão financeira já combinada - por exemplo "Desistência do cliente, acordado estorno integral via PIX em até 5 dias úteis" ou "Cancelamento com retenção de 30% conforme cláusula 8 do contrato".
3. Clique em Confirmar Cancelamento. Toast: "Reserva cancelada com sucesso!".

Neste momento o sistema:

• Muda o status do passageiro para Cancelado e do financeiro para cancelado (cancelado = true, cancelado_obs = motivo).
• Se o passageiro era o titular/comprador do pedido, cancela automaticamente todos os outros passageiros não-cancelados do mesmo order_id (grupo inteiro). Quando é só um acompanhante, ajusta o valor original e o pendente do titular e da Order.
• Apaga a alocação de quarto (registros em QuartoPassageiro).

O sistema não toca nos pagamentos confirmados - eles continuam com status Confirmado mesmo depois do cancelamento, justamente para que o histórico financeiro fique íntegro até você registrar o estorno.

Passo 3 - Tratar o dinheiro conforme o cenário

Siga uma das seções de Casos especiais abaixo, conforme o tipo de pagamento e a política aplicada.

Casos especiais

Cenário 1 - Pagamento ainda pendente (não cobrado)

Aplica-se a parcelas agendadas no Plano de Pagamentos com status Pendente e sem data de pagamento. Não houve entrada de dinheiro.

1. Cancele a reserva normalmente (Passo 2). O financeiro vai a cancelado e as parcelas pendentes permanecem na tela apenas para histórico - não geram cobrança nem aparecem em relatórios de recebíveis (o financeiro está cancelado).
2. Não é necessário excluir as parcelas. Se quiser limpar a tela, pode usar o botão Excluir (vermelho) em cada parcela pendente.
3. Não há nada a estornar.

Cenário 2 - Pagamento manual aprovado (PIX direto, dinheiro, transferência)

O cliente já entregou o dinheiro fora do meio de pagamento e você confirmou o pagamento na mão (origem manual ou pix_direto).

Decisão 1: estorno integral

1. Cancele a reserva (Passo 2) registrando no motivo "Estorno integral acordado".
2. Faça a devolução do dinheiro pelo canal apropriado (PIX de volta na chave do cliente, transferência, etc.). Isso é uma operação externa ao Viagilize.
3. Para registrar o estorno no sistema, abra o pagamento na seção Plano de Pagamentos e use o fluxo de estorno do Viagilize: o model ExcursaoPassageiroPagamento::estornar() marca estornado = true, registra estornado_em, estornado_por, estornado_motivo, estornado_valor e soma esse valor em valor_reembolsado do financeiro. Quando valor_reembolsado >= valor_pago, o financeiro passa para status Reembolsado.

Decisão 2: estorno parcial (retém multa)

1. Cancele a reserva (Passo 2) descrevendo a multa: "Cancelamento com retenção de R$ X conforme política".
2. Devolva ao cliente apenas o valor líquido (total pago menos multa) pelo canal externo.
3. Estorne no Viagilize informando o valor devolvido (não o total pago). O campo estornado_valor aceita valor parcial; o que sobrar conta como valor efetivamente retido pela empresa.
4. O lançamento original fica como Confirmado + Estornado parcial. O valor_pago permanece, e a empresa preserva no resultado da excursão o valor da multa.

Decisão 3: converter em crédito futuro

1. Cancele a reserva (Passo 2) registrando "Cancelado com crédito para próxima excursão - combinar uso na nova reserva".
2. Não estorne o pagamento - ele fica como Confirmado vinculado ao financeiro cancelado.
3. Quando o cliente fizer a nova reserva, registre nela um pagamento manual com a observação cruzada ("Crédito da reserva cancelada #ABC - pagamento original em DD/MM/AAAA"). O Viagilize não tem um "saldo de crédito" formal por cliente: a rastreabilidade é via observação do pagamento e histórico do cliente.

Cenário 3 - Pagamento via meio de pagamento (PIX/cartão pelo checkout)

Pagamentos com Origem Mercado Pago, Asaas, Pagar.me ou InfinitePay têm regra própria: não podem ser editados nem excluídos pelo admin no Viagilize (o método isManual() retorna false e a tela de pagamento bloqueia esses botões).

1. Cancele a reserva no Viagilize (Passo 2). Isso libera a vaga e marca o financeiro como cancelado, mas não envia comando de estorno para o meio de pagamento.
2. Entre no painel do meio de pagamento de origem (Mercado Pago, Asaas, Pagar.me ou InfinitePay) e dispare o estorno/reembolso lá. Use o campo codigo_transacao ou referencia_externa do pagamento (visível no detalhe do lançamento) para localizar a transação.
   • PIX: prazo típico de devolução de até 24h pelo banco do pagador.
   • Cartão de crédito: estorno aparece na próxima fatura ou em até 2 ciclos, dependendo do banco emissor. Para parcelas já cobradas, o meio de pagamento costuma estornar todas as parcelas proporcionalmente.
3. Volte ao Viagilize e estorne o pagamento no sistema (botão de estorno do Plano de Pagamentos), informando no motivo a referência do estorno do meio de pagamento. Isso mantém o financeiro do passageiro coerente com o caixa real.

Cenário 4 - Política de cancelamento da empresa (multa retida)

A política (escala de multa por antecedência, taxa fixa, valor mínimo retido) não é configurada automaticamente no Viagilize hoje - ela vive no contrato/termos da sua empresa e é aplicada manualmente pelo atendente. O fluxo prático:

1. Antes de cancelar, calcule o valor a reter conforme a regra interna (ex.: 100% até 30 dias antes, 50% entre 30 e 15 dias, 0% nos últimos 15 dias).
2. Comunique o cliente o valor líquido a devolver e o valor retido, citando a cláusula do contrato.
3. Siga o Cenário 2 (Decisão 2) ou Cenário 3 com o valor parcial.
4. Registre o valor retido como observação no pagamento estornado. A diferença entre valor_pago original e estornado_valor é exatamente a multa retida - útil para o relatório financeiro da excursão.

Cenário 5 - Saldo do financeiro do passageiro após o cancelamento

Após o Passo 2, o card Financeiro mostra a reserva com status Cancelado (o atualizarStatus() define 'cancelado' quando cancelado = true). Ao processar estornos:

• Cada estorno soma em valor_reembolsado.
• Quando valor_reembolsado >= valor_pago, o status muda para Reembolsado.
• O valor_pago é recalculado por sincronizarValorPago() somando apenas pagamentos confirmado e estornado = false. Pagamentos totalmente estornados deixam de contar como pagos.
• Para um titular de grupo, o financeiro do titular agrega valores de todos os passageiros do mesmo order_id. Cancelar um acompanhante já ajusta valor_original, valor_total e valor_pendente do titular - verifique esses números antes de estornar para não devolver o que pertencia a outro passageiro.

Erros comuns e como resolver

• "Esta reserva não pode ser cancelada." - Causa: status atual não permite (Cancelado, Transferido, No Show) ou já há check-in feito. Solução: confira o status; se houve check-in indevido, peça ao operacional para reverter antes.
• "Este pagamento não pode ser editado." ou "Este pagamento não pode ser excluído." - Causa: pagamento veio de meio de pagamento (não manual) ou já está estornado. Solução: para meio de pagamento, faça o estorno no painel do próprio meio de pagamento e depois marque o estorno no Viagilize pelo fluxo de estornar, não pelo Editar/Excluir.
• Cliente reclama que cancelou e ainda foi cobrado pelo cartão - Causa: cancelamento no Viagilize não dispara estorno no meio de pagamento. Solução: entre no painel do meio de pagamento e dispare o reembolso manualmente (Cenário 3).
• Saldo do titular continua positivo depois de cancelar acompanhante
  • Causa: o estorno do pagamento ainda não foi feito; o cancelamento do acompanhante ajusta o valor cobrado, mas o que já estava pago permanece como crédito do titular. Solução: estorne o pagamento correspondente ou aplique como crédito em outra reserva.
• Quero excluir uma parcela de meio de pagamento que não foi cobrada - Causa: parcela vinda do meio de pagamento não pode ser excluída pelo admin. Solução: cancele a reserva inteira (o financeiro cancelado anula a cobrança) e, se necessário, peça ao suporte para limpar o registro.

Onde encontrar

• URL principal: /admin/reservas/{passageiro} (a ação de cancelar e o tratamento dos pagamentos acontecem todos nesta tela)
• Caminho no menu: Reservas (item fixo do sidebar) - abra a reserva específica e use os controles em Ações e Plano de Pagamentos
• Permissão necessária: editar as reservas para cancelar e para registrar/estornar pagamentos; ver as reservas para consultar
• Módulo necessário: nenhum (faz parte do núcleo de Reservas)
• Painéis externos envolvidos: Mercado Pago, Asaas, Pagar.me ou InfinitePay - usados para o estorno efetivo de pagamentos que passaram por meio de pagamento

Veja também

• Reservas - Cancelar Reserva
• Reservas - Pagamentos da Reserva
• Fluxos - Reembolsar o Cliente