Passageiros - Status do Passageiro

O que é

O status é a etiqueta que identifica em que ponto do ciclo de vida cada passageiro está dentro da excursão. Ele aparece como um badge colorido ao lado do nome na listagem em "/admin/excursoes/{excursao}/passageiros" e governa o que o sistema permite (check-in, transferência, edição) ou bloqueia para cada reserva.

Você costuma chegar nesta tela ao abrir uma excursão e olhar a aba Passageiros: é onde a equipe de atendimento confere quem está confirmado para embarque, quem ainda precisa pagar, quem desistiu e quem precisa ser cobrado ou transferido. A maioria das mudanças de status acontece automaticamente - confirmação por pagamento, expiração de PIX, cancelamento em cascata pela Order - mas todas podem ser ajustadas manualmente pelo administrador quando necessário.

Como usar

Significado de cada status

O sistema trabalha com seis status (definidos em ExcursaoPassageiro::getStatusLabelAttribute):

• Confirmado (verde) - Reserva ativa e confirmada. O passageiro conta para o mapa de assentos, entra nas listas de embarque, recebe voucher/cartão de embarque e pode fazer check-in. Quando o financeiro chega a pago, o método confirmarReserva() move o passageiro para este status e limpa pagamento_expira_em.

• Pendente (amarelo) - Reserva criada, ainda aguardando pagamento ou confirmação manual. Continua ocupando vaga no transporte e na excursão (entra em scopeAtivos), aparece no mapa de assentos e pode ter pagamento lançado. Reservas vindas do site nascem aqui quando o pagamento ainda não foi compensado.

• Cancelado (vermelho) - Reserva encerrada. Libera assento, libera vaga em quartos de hospedagem, cancela o financeiro, gera contra-lançamento das receitas já confirmadas e dispara o webhook reserva.cancelada (quando não faz parte de uma Order). Continua visível na lista quando o filtro de Status está em Cancelado; fora desse filtro, fica oculto por padrão.

• Transferido (roxo) - Passageiro migrado para outra excursão pelo fluxo de Transferir p/ outra Excursão. O registro original fica no histórico desta excursão como referência, mas o passageiro ativo passa a ser o novo registro criado na excursão de destino. Igual ao Cancelado, não conta mais para vagas nem aparece em mapas/listas.

• Não Compareceu (cinza) - Marcação manual para registrar que o passageiro faltou ao embarque. Útil para relatórios de comparecimento e análise de no-show. Diferente de Cancelado, não desfaz pagamento nem dispara webhook de cancelamento.

• Lista de Espera (azul) - Status legado de passageiros que entraram na fila quando a excursão estava cheia. O sistema atual trata lista de espera em uma tabela própria (acessada pelo botão Lista de Espera logo abaixo dos filtros), mas o badge continua reconhecido na listagem para reservas antigas.

O que dispara cada transição

De → Para	Gatilho
(novo) → Pendente	Cadastro com status Pendente no modal Adicionar Passageiro, ou checkout no site quando o pagamento ainda não compensou
(novo) → Confirmado	Cadastro com status Confirmado no modal Adicionar Passageiro, ou checkout com pagamento à vista aprovado
Pendente → Confirmado	ExcursaoPassageiro::confirmarReserva() quando o financeiro fica pago (webhook de meio de pagamento, pagamento manual lançado etc.)
Pendente → Cancelado	cancelarPorExpiracao() quando pagamento_expira_em passa há mais de 5 minutos (job de expiração), ou cancelamento manual pelo dropdown Cancelar
Confirmado/Pendente → Cancelado	Botão Cancelar no dropdown de ações da linha, exigindo motivo obrigatório (até 500 caracteres)
Confirmado/Pendente → Transferido	Botão Transferir p/ outra Excursão no dropdown de ações; o status só vira Transferido se o passageiro original não tiver feito check-in
Confirmado → Não Compareceu	Alteração manual no modal Editar, salvando com Status = no_show

Mudar o status para Confirmado vindo de outro estado dispara o ExcursaoPassageiroWhatsAppObserver::updated, que envia a confirmação da reserva e o cartão de embarque (quando o passageiro está apto). Mudar para Cancelado envia a mensagem de cancelamento. Pedidos com mais de um passageiro têm a mensagem consolidada no nível da Order para evitar disparo duplicado.

O que cada status libera ou bloqueia

• Confirmado e Pendente (estados ativos, estaAtivo() retorna true): contam para vagas do transporte (scopeAtivos), aparecem no mapa de assentos, podem ser editados, podem ser transferidos (podeTransferir()), podem ser cancelados (podeCancelar(), desde que ainda não tenham feito check-in) e recebem cartão de embarque automático quando ficam aptos.

• Confirmado especificamente: é o único estado em que o passageiro entra no fluxo de check-in/embarque com voucher e QR Code válidos.

• Cancelado, Transferido e Não Compareceu: não contam para vagas (vagasOcupadasTransporte filtra por confirmado/pendente), não bloqueiam assento (assentoOcupado ignora cancelados e transferidos), não recebem mais notificações automáticas, não podem ser transferidos e não podem ser cancelados novamente. Um passageiro Cancelado sem financeiro vinculado pode ser excluído definitivamente pelo método destroy.

Mudar o status manualmente

1. Vá em Excursões > {Excursão} > Passageiros.
2. Localize a linha do passageiro e abra o dropdown de ações no final da linha.
3. Para alternar entre Pendente e Confirmado, clique em Editar, ajuste o campo Status no modal e clique em Salvar. O seletor só permite os valores aceitos pelo controller: pendente, confirmado, cancelado e no_show.
4. Para mover para Cancelado, clique em Cancelar no dropdown, preencha o motivo (obrigatório) e confirme em Confirmar Cancelamento.
5. Para mover para Transferido, clique em Transferir p/ outra Excursão, escolha a excursão de destino, complete os dados de embarque/categoria/valor e confirme. O passageiro original fica marcado como Transferido e um novo passageiro Confirmado/Pendente é criado na excursão de destino.

Filtrar por status na listagem

1. Na barra de filtros, clique em Status (segundo seletor a partir da esquerda).
2. Escolha Confirmado, Pendente ou Cancelado. O padrão Todos (exceto cancelados) mostra apenas reservas ativas; é o modo que a equipe usa no dia a dia.
3. O contador entre parênteses ao lado de Cancelado indica quantos passageiros cancelados existem na excursão.

Casos especiais

Reserva expirada por falta de pagamento

Reservas em Pendente com pagamento_expira_em no passado entram no scopeExpiradas (com margem de 5 minutos para absorver atraso de webhook PIX) e podem ser canceladas em lote pelo job que roda periodicamente. O método chamado é cancelarPorExpiracao(), que grava o motivo "Reserva cancelada automaticamente por falta de pagamento no prazo." e dispara o webhook reserva.expirada para passageiros sem Order.

Dependentes herdam status do titular

Passageiros marcados como dependente (dependente_id preenchido) não têm pagamento próprio: o titular do grupo é quem paga e quem aceita o contrato. Por isso pagamentoRealizado() e aceitouContrato() consultam o titular antes de retornar true. Cancelar o titular não cancela automaticamente os dependentes - eles ficam órfãos até serem cancelados ou reanexados a outro titular.

Passageiro com check-in já feito

Mesmo estando Confirmado, um passageiro que já passou pelo embarque (fezCheckin() retorna true) não pode mais ser cancelado pelo botão Cancelar nem transferido pelo fluxo de transferência. O endpoint transferirExecutar rejeita com erro 422 "Não e possível transferir um passageiro que ja fez check-in".

Membro de grupo (passageiro extra)

Quando o passageiro foi adicionado como poltrona extra no grupo (cadastrado_via = admin_grupo), cancelar essa reserva subtrai o valor cobrado do financeiro do titular do grupo, recalculando valor_original, valor_total e valor_pendente antes de marcar o cancelamento.

Excluir versus cancelar

O botão Excluir (rota destroy) só funciona para passageiros já em Cancelado que não tenham financeiro vinculado. Para qualquer outro caso, o caminho correto é cancelar pela rota cancelar, preservando histórico, motivo, lançamentos contábeis revertidos e webhook de cancelamento.

Erros comuns e como resolver

• "Apenas passageiros cancelados podem ser excluídos. Cancele primeiro." - Causa: tentativa de usar Excluir em passageiro Confirmado ou Pendente. Solução: cancelar antes pelo botão Cancelar e depois excluir, caso queira remoção definitiva.
• "Não é possível excluir passageiro com financeiro vinculado." - Causa: passageiro Cancelado mas com lançamentos financeiros associados. Solução: manter o passageiro como Cancelado para preservar histórico contábil.
• "Este passageiro não pode ser transferido" - Causa: status diferente de Confirmado/Pendente (já está Cancelado, Transferido ou Não Compareceu). Solução: somente passageiros ativos podem ser transferidos.
• "Não e possível transferir um passageiro que ja fez check-in" - Causa: passageiro já fez check-in. Solução: avaliar se o caso é mesmo de transferência ou se deve ser tratado como reembolso/crédito separado.
• "Este cliente ja esta cadastrado na excursão de destino" - Causa: cliente já tem reserva ativa na excursão de destino. Solução: cancelar a reserva antiga ou ajustar a transferência manualmente.
• Passageiro Cancelado some da lista - Causa: filtro Status está em Todos (exceto cancelados), comportamento padrão. Solução: trocar o filtro para Cancelado para visualizá-los.

Onde encontrar

• URL: /admin/excursoes/{excursao}/passageiros
• Caminho no menu: Excursões > {Excursão} > Passageiros
• Permissão necessária: ver as viagens, ver os passageiros
• Módulo necessário: nenhum

Veja também

• Visão geral dos Passageiros
• Cadastrar passageiro
• Cancelamento e Transferência
• Financeiro do Passageiro
• Check-in e Embarque