Passageiros - Cancelar e Transferir

O que é

Esta página descreve as três ações destrutivas/realocadoras disponíveis na linha de cada passageiro da listagem da excursão: Cancelar (marca a reserva como cancelada e atualiza o financeiro), Excluir (remove o registro de forma permanente, só para passageiros já cancelados e sem financeiro vinculado) e Transferir p/ outra Excursão (move o passageiro para outra excursão publicada em um fluxo guiado de 3 passos).

O admin normalmente chega aqui quando o cliente desiste da viagem, quando o pagamento expira, quando a empresa precisa reagrupar excursões ou quando o cliente quer remarcar para outra data. Todas as ações partem do mesmo dropdown na linha do passageiro, dentro da aba Passageiros da edição da excursão.

Como usar

Cancelar um passageiro

1. Vá em Viagens (Excursões) no menu lateral e abra a excursão.
2. Acesse a aba Passageiros.
3. Na linha do passageiro, abra o dropdown de ações (ícone três pontos) e clique em Cancelar.
4. No modal Cancelar Passageiro, preencha o campo Motivo do cancelamento (obrigatório, até 500 caracteres).
5. Clique em Confirmar Cancelamento.

O que o sistema faz ao confirmar:

• Muda o status do passageiro para cancelado, grava cancelado_em, cancelado_por (usuário logado) e cancelado_motivo.
• Libera o assento atual (campo assento é zerado).
• Marca o ExcursaoPassageiroFinanceiro vinculado como status = cancelado e dispara o serviço VendaFinanceiroSyncService::cancelarVenda, que cancela contas a receber pendentes e gera contra-lançamento das receitas já confirmadas no módulo Gestão Financeira.
• Remove a vaga do passageiro em quartos de hospedagem (QuartoPassageiro).
• Recalcula valor_total, valor_original e valor_pendente da Order, considerando apenas passageiros ativos (confirmado/pendente).
• Invalida o aceite de contrato do grupo do comprador na excursão (via ContratoService::invalidarAceiteGrupo) - todos os passageiros que assinaram o mesmo contrato precisarão reassinar.
• Dispara o job ProcessarListaEspera após 10 segundos, se a lista de espera estiver ativa na configuração de Jornada do Cliente.
• Reverte o claim de lista de espera, se o passageiro tinha entrado por essa via.
• Dispara o webhook reserva.cancelada (apenas quando o passageiro não pertence a uma Order - quando pertence, a notificação sai do Order::cancelar para evitar duplicidade).

Excluir um passageiro cancelado

A exclusão permanente só aparece como ação quando o passageiro já está com status cancelado.

1. Localize o passageiro cancelado na listagem (use o filtro de status para encontrar mais rápido).
2. Abra o dropdown de ações e clique em Excluir.
3. Confirme no modal Excluir Passageiro. A ação não pode ser desfeita.

Bloqueios automáticos:

• Tentativa de excluir um passageiro com status diferente de cancelado devolve "Apenas passageiros cancelados podem ser excluídos. Cancele primeiro."
• Passageiro com ExcursaoPassageiroFinanceiro vinculado (mesmo que zerado) devolve "Não é possível excluir passageiro com financeiro vinculado." - nesse caso a operação correta é manter como cancelado.

Transferir para outra excursão

1. Na linha do passageiro, abra o dropdown e clique em Transferir p/ outra Excursão.
2. Passo 1 - Excursão: o sistema lista todas as excursões com status = publicada e data_inicio futura (excluindo a atual). Use a busca pelo nome para filtrar e clique no card da excursão destino.
3. Passo 2 - Configurar: o sistema mostra um comparativo DE / PARA (transporte, embarque, categoria, assento, valor cobrado e pago da origem vs. o que está sendo configurado no destino). Selecione:
   • Transporte (oculto se a excursão destino for pacote_viagem ou não tiver transportes cadastrados).
   • Embarque (oculto se a excursão destino não tiver embarques).
   • Categoria (obrigatório).
   • Valor a cobrar (R$) - preenchido automaticamente pelo buscarPrecoDestino sempre que algum dropdown muda, mas é editável.
   • Transferir N dependente(s) junto - checkbox amarelo que só aparece quando o passageiro tem dependentes no grupo.
4. Clique em Revisar e Confirmar para avançar ao passo 3.
5. Passo 3 - Confirmar: revise o resumo (origem marcada como transferido, nova reserva no destino, crédito disponível se houver, valor pendente a cobrar, contrato invalidado, assento liberado) e preencha o campo Motivo da transferência (obrigatório).
6. Clique em Confirmar Transferência.

O que o sistema faz ao executar:

• Aplica lockForUpdate no passageiro de origem para impedir transferências duplicadas em paralelo.
• Verifica a capacidade do transporte destino (com lock) e aborta se estiver lotado.
• Origem: muda status para transferido, libera o assento, marca o financeiro como cancelado, invalida o contrato do grupo na origem e dispara processamento da lista de espera, então faz soft-delete do passageiro origem para sumir das listagens.
• Destino: cria nova Order (ou reaproveita a do titular quando se trata de dependente), cria o novo ExcursaoPassageiro com status confirmado, gera novo qr_code e codigo_reserva, e copia os dados pessoais.
• Registra um TransferenciaExcursaoLog com snapshot do estado antes e depois.
• Silencia observers (não envia WhatsApp/e-mail de cancelamento na origem nem de confirmação no destino - a comunicação com o cliente sobre a transferência fica a cargo do operador).

Casos especiais

Membro de grupo (admin_grupo)

Quando o passageiro foi cadastrado via grupo (cadastrado_via = admin_grupo) e pertence a uma Order, o cancelamento subtrai o valor_cobrado desse passageiro do valor_original do financeiro do titular da Order (passageiro com cadastrado_via em admin_manual ou checkout_order e status ativo). O valor_total, valor_pendente e status (pago se zerar a pendência) do titular são recalculados. Isso evita que o titular continue devendo a parte de um membro que saiu do grupo.

Passageiro com check-in feito

A ação Transferir p/ outra Excursão desaparece do dropdown quando podeTransferir() retorna false (passageiro não está em confirmado/pendente) ou quando fezCheckin() é verdadeiro. Para transferir um passageiro que já fez check-in é preciso primeiro reverter o check-in no app do guia.

Cliente já cadastrado na excursão destino

Antes de executar a transferência, o sistema checa se o cliente_id do passageiro já existe na excursão de destino com status diferente de cancelado/transferido. Se existir, devolve "Este cliente ja esta cadastrado na excursão de destino" e a operação é abortada - nesse caso é preciso decidir qual reserva manter manualmente.

Diferença de valores no destino

O resumo do passo 3 mostra três linhas que dependem do que o preview() calcula:

• Diferença: valorCobrado - valor_cobrado_origem. Positivo (vermelho) significa que o destino é mais caro; negativo (verde) significa que sobrou crédito.
• Crédito disponível: o que já foi pago na origem e não foi reembolsado. Aplicado automaticamente ao novo passageiro.
• Pendente a cobrar: valorCobrado - credito_aplicado. Se positivo, fica registrado na nova Order como pendência para o cliente quitar.

Dependentes do mesmo titular

Quando o passageiro é titular e tem dependentes ativos no mesmo grupo, aparece o checkbox Transferir N dependente(s) junto. Marcado, os dependentes são movidos na mesma transação e reaproveitam a Order recém-criada no destino (não se cria uma Order por dependente).

Excursão destino não publicada

Se entre o preview e o execute alguém despublicar a excursão destino, o execute devolve "A excursão de destino não esta publicada" e nada é aplicado.

Pacote de viagem (sem transporte)

Excursões com tipo_excursao = pacote_viagem não exibem o seletor de Transporte no passo 2 e não validam capacidade de veículo. Embarque continua disponível se a excursão destino tiver pontos cadastrados.

Erros comuns e como resolver

• "Passageiro não pertence a esta excursão" - Causa: o excursao_id do passageiro não bate com o da rota (geralmente URL adulterada ou cache antigo). Solução: recarregar a página e tentar pelo dropdown novamente.
• "Apenas passageiros cancelados podem ser excluídos. Cancele primeiro." - Causa: tentativa de excluir um passageiro ainda ativo. Solução: cancelar primeiro pela ação Cancelar, depois usar Excluir.
• "Não é possível excluir passageiro com financeiro vinculado." - Causa: existe registro em excursao_passageiros_financeiro mesmo após cancelamento. Solução: manter como cancelado - o histórico financeiro precisa ser preservado para conciliação.
• "Este passageiro não pode ser transferido" - Causa: status fora de confirmado/pendente (já cancelado, transferido, no-show). Solução: rever o status antes de tentar transferir.
• "Não e possível transferir um passageiro que ja fez check-in" - Causa: o passageiro tem registro em ExcursaoCheckin. Solução: pedir ao guia para reverter o check-in no app antes de transferir.
• "Este cliente ja esta cadastrado na excursão de destino" - Causa: existe outro passageiro do mesmo cliente ativo na excursão escolhida. Solução: cancelar a duplicata na destino ou escolher outra excursão.
• "O veículo '{nome}' no destino está lotado - escolha outro transporte ou aguarde liberar vaga." - Causa: capacidade do excursao_transporte selecionado se esgotou entre o preview e o execute. Solução: voltar ao passo 2 e selecionar outro transporte ou tirar a seleção (se o destino aceitar passageiro sem transporte).
• "Este passageiro ja foi transferido. Recarregue a página." - Causa: duplo-clique no botão Confirmar - a segunda chamada perde o lock e encontra o passageiro já marcado como transferido. Solução: recarregar a página; a transferência da primeira chamada está aplicada.
• "A excursão de destino não esta publicada" - Causa: a excursão destino foi despublicada após a seleção. Solução: voltar ao passo 1 e escolher outra excursão publicada.

Onde encontrar

• URL: /admin/excursoes/{excursao}/passageiros
• Endpoint Cancelar: POST /admin/api/excursoes/{excursao}/passageiros/{passageiro}/cancelar
• Endpoint Excluir: DELETE /admin/excursoes/{excursao}/passageiros/{passageiro}
• Endpoint Listar destinos da transferência: GET /admin/api/excursoes/{excursao}/passageiros/{passageiro}/transferir-excursao/excursoes
• Endpoint Preview da transferência: GET /admin/api/excursoes/{excursao}/passageiros/{passageiro}/transferir-excursao/preview
• Endpoint Preço no destino: GET /admin/api/excursoes/{excursao}/passageiros/{passageiro}/transferir-excursao/preco
• Endpoint Executar transferência: POST /admin/api/excursoes/{excursao}/passageiros/{passageiro}/transferir-excursao
• Caminho no menu: Viagens (Excursões) > {excursão} > Passageiros
• Permissões necessárias: ver as viagens para acessar a listagem, editar as viagens para cancelar/excluir/transferir
• Módulo necessário: nenhum (faz parte do core de excursões); a sincronia com contas a receber acontece automaticamente quando o módulo Gestão Financeira está ativo

Veja também

• Status do Passageiro - entenda os estados cancelado, transferido e no-show que essas ações produzem.
• Financeiro do Passageiro - confira como o cancelamento reflete em reembolsos, créditos e contas a receber.
• Cadastrar Passageiro - ponto de partida do ciclo de vida do passageiro.
• Voucher e QR Code - o voucher antigo é invalidado e um novo é emitido na transferência.