Reservas - Status da Reserva

O que é

O status da reserva é a etiqueta que indica em que ponto do ciclo de vida cada reserva está dentro da lista global de "/admin/reservas". Ele aparece como um badge colorido ao lado do nome do passageiro e governa o que o sistema permite ou bloqueia: cancelamento, reativação, exclusão definitiva, envio de cartão de embarque e contagem para vagas da excursão.

Você costuma chegar nesta tela vindo de Reservas no menu lateral para conferir, em um único lugar, todas as reservas da sua empresa - independente da excursão. É o mesmo conceito de status que aparece na aba Passageiros dentro de cada excursão (ver Passageiros - Status do Passageiro); o módulo Reservas apenas exibe o mesmo registro excursao_passageiros sob um filtro global por empresa, somando o status financeiro derivado do pagamento ao lado do status canônico da reserva.

Como usar

Significado de cada status

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

• Confirmado (verde) - Reserva ativa e paga. O passageiro conta para o mapa de assentos, entra nas listas de embarque, recebe voucher e cartão de embarque e pode fazer check-in. Quando o financeiro fica pago, ExcursaoPassageiro::confirmarReserva() move a reserva para este status e limpa o prazo de expiração.

• Pendente (amarelo) - Reserva criada, aguardando pagamento ou confirmação manual. Continua ocupando vaga e aparece na lista normalmente, mas ainda não recebeu o pagamento que completa a compra. Reservas vindas do site nascem aqui enquanto o meio de pagamento não compensa o valor. Funciona como "rascunho operacional" - a reserva existe, mas ainda não está garantida.

• Cancelado (vermelho) - Reserva encerrada. Libera assento, libera vaga em quartos, cancela o financeiro, gera contra-lançamento das receitas já confirmadas e dispara o webhook reserva.cancelada quando a reserva não faz parte de uma Order maior. Por padrão a listagem de Reservas esconde canceladas - só aparecem ao escolher Cancelado no filtro de Status.

• Transferido (roxo) - A reserva foi migrada para outra excursão pelo fluxo de transferência (acessado pela aba Passageiros da excursão de origem). O registro original fica como histórico nesta excursão e um novo passageiro Confirmado/Pendente é criado no destino. O módulo Reservas não tem botão de transferência próprio, mas mostra o badge roxo quando o status já foi alterado.

• Não Compareceu (cinza) - Marcação manual usada quando o passageiro faltou ao embarque. Útil para relatórios de no-show. Diferente de Cancelado, não desfaz o financeiro nem envia notificação automática de cancelamento.

• Lista de Espera (azul) - Status legado de reservas que entraram em fila quando a excursão estava cheia. O fluxo atual de lista de espera tem tabela própria, mas o badge azul continua sendo reconhecido para reservas antigas.

Status da reserva vs status do pagamento

Na listagem em "/admin/reservas" cada linha exibe dois badges lado a lado:

1. Status da reserva - o valor canônico salvo em excursao_passageiros.status (Pendente, Confirmado, Cancelado, Lista Espera). É o que esta página documenta.
2. Status do pagamento - calculado em tempo real a partir de valor_pago e valor_pendente da Order ou do financeiro, com os rótulos Pago (verde), Parcial (laranja), Pgto Pendente (amarelo) ou Cancelado (vermelho).

Isso significa que uma reserva pode estar Confirmado + Pgto Pendente (confirmada manualmente antes do pagamento entrar) ou Pendente + Parcial (cliente já pagou parte mas ainda não fechou). O filtro Status no topo combina os dois conceitos: ao escolher Confirmado lá, o controller filtra por reservas não canceladas cujo valor pendente é zero, e não pelo campo status em si.

O que dispara cada transição

De para	Gatilho
(novo) para Pendente	Cadastro com status Pendente no modal de criação, ou checkout no site enquanto o pagamento ainda não compensou
(novo) para Confirmado	Cadastro já marcado como Confirmado, ou checkout com pagamento aprovado à vista
Pendente para Confirmado	ReservaAdminController::confirmar (botão Confirmar no dropdown da linha), ou automático quando o financeiro fica pago via confirmarPagamento / webhook do meio de pagamento
Pendente para Cancelado	ReservaAdminController::cancelar (botão Cancelar, motivo obrigatório de até 500 caracteres), ou ExcursaoPassageiro::cancelarPorExpiracao() quando o prazo de pagamento expira há mais de 5 minutos
Confirmado para Cancelado	Mesmo ReservaAdminController::cancelar, desde que a reserva ainda não tenha feito check-in
Cancelado para Pendente	ReservaAdminController::reativar (botão Reativar, restaura soft-delete se necessário e reabre o financeiro como Pendente)
Confirmado/Pendente para Transferido	Fluxo de transferência (ExcursaoPassageiroController::transferirExecutar), acionado pela aba Passageiros da excursão de origem
Confirmado para Não Compareceu	Alteração manual na edição da reserva, salvando o status como no_show

Badges visuais

As cores usadas na listagem (resources/views/admin/reservas/index.blade.php) seguem o padrão:

• Confirmado - fundo verde-claro com texto verde-escuro.
• Pendente - fundo âmbar com texto âmbar-escuro.
• Cancelado - fundo vermelho-claro com texto vermelho-escuro.
• Lista Espera - fundo azul-claro com texto azul-escuro.
• Transferido / Não Compareceu - exibidos no cartão da excursão (aba Passageiros) com badges roxo e cinza respectivamente; na listagem global de Reservas costumam aparecer apenas em filtros específicos por estarem fora do recorte padrão.

A borda lateral esquerda do cartão usa a mesma família de cor do status do pagamento (verde = Pago, laranja = Parcial, amarelo = Pendente, vermelho = Cancelado) para dar o resumo visual rápido.

Filtrar por status na listagem

1. Vá em Reservas no menu lateral.
2. Na barra de filtros, abra o seletor Status (segundo campo à direita da busca).
3. Escolha uma das opções: Todos os status, Pendente, Parcial, Confirmado ou Cancelado.
4. Parcial e Confirmado filtram pelo status do pagamento (não pelo campo status da reserva), considerando os valores agregados da Order quando existir.
5. O padrão Todos os status já esconde reservas com valor zero e convites pendentes - para ver canceladas é obrigatório selecionar Cancelado explicitamente.

Mudar o status manualmente

1. Localize a reserva na listagem em "/admin/reservas".
2. Abra o dropdown de ações na linha.
3. Para confirmar uma reserva Pendente, clique em Confirmar. O controller só aceita a chamada se o status atual for pendente.
4. Para cancelar, clique em Cancelar, preencha o motivo obrigatório (até 500 caracteres) e confirme. O cancelamento passa pelo ReservaService::cancelarReserva, que cuida do financeiro e das notificações.
5. Para reativar uma reserva Cancelada, clique em Reativar. Ela volta para Pendente, o soft-delete é desfeito e o financeiro reabre com status Pendente. Se houver Order vinculada também cancelada, ela volta para o status pendente da Order.
6. Para excluir definitivamente, clique em Excluir (só aparece em reservas já Canceladas). O sistema aplica soft-delete e bloqueia a exclusão se ainda houver financeiro vinculado.

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 de expiração. 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 reservas sem Order. Na listagem elas passam a aparecer apenas com o filtro Cancelado ativo.

Confirmação por pagamento aprovado

Quando um pagamento é confirmado por ReservaAdminController::confirmarPagamento (manual) ou por webhook do meio de pagamento, o financeiro vira pago. Em seguida o controller verifica $financeiro->status === 'pago' && $passageiro->status === 'pendente' e promove a reserva para Confirmado automaticamente. Por isso, na prática, o usuário raramente precisa clicar em Confirmar - basta registrar o pagamento.

Comprador titular de grupo

Em compras de grupo (titular + dependentes/convidados), a listagem de Reservas mostra apenas a linha do titular comprador. O status exibido é o do titular, mas o cancelamento dele cancela o financeiro do grupo. Dependentes mantêm seus status próprios e podem ficar órfãos se o titular for cancelado sem reanexação.

Confirmar versus Reativar

Os dois fluxos terminam com a reserva em estado utilizável, mas têm origem diferente:

• Confirmar só funciona em reservas Pendente e marca como Confirmado. Usado quando o cliente já pagou (ou o gestor quer garantir a vaga antes do pagamento entrar).
• Reativar só funciona em reservas Cancelado e volta para Pendente. Restaura o soft-delete e reabre o financeiro; depois disso, ainda é preciso receber o pagamento ou clicar em Confirmar novamente.

Erros comuns e como resolver

• "Esta reserva não pode ser confirmada." - Causa: chamada de Confirmar em reserva cujo status não é pendente (já está Confirmado, Cancelado, Transferido ou Não Compareceu). Solução: usar o fluxo correspondente ao estado atual (Reativar para Cancelado, edição manual nos demais).
• "Apenas reservas canceladas podem ser reativadas." - Causa: tentativa de Reativar uma reserva que não está Cancelado. Solução: nenhum, o botão só faz sentido para canceladas; ignorar para outros status.
• "Apenas reservas canceladas podem ser excluídas." - Causa: uso do Excluir em reserva Pendente ou Confirmado. Solução: cancelar antes pelo botão Cancelar e depois excluir, se quiser remoção definitiva.
• Reserva Cancelada some da listagem - Causa: o filtro padrão Todos os status esconde canceladas. Solução: trocar o filtro para Cancelado para visualizá-las.
• Badge da reserva mostra Confirmado mas o pagamento aparece como Pgto Pendente - Causa: alguém clicou em Confirmar antes do pagamento entrar. Solução: registrar o pagamento; quando ele for confirmado, o badge do pagamento muda sozinho para Pago.

Onde encontrar

• URL: /admin/reservas
• Caminho no menu: Reservas
• Permissão necessária: ver as reservas (visualizar status), editar as reservas (mudar status, cancelar, reativar), excluir as reservas (excluir cancelada)
• Módulo necessário: nenhum

Veja também

• Visão geral das Reservas
• Lista de Reservas
• Confirmar reserva
• Cancelar reserva
• Pagamentos da reserva
• Passageiros - Status do Passageiro