Excursões - Lista de Espera

O que é

A Lista de Espera é a fila de interessados de uma excursão que está esgotada (ou que ainda terá capacidade aberta no futuro). Cada entrada guarda o contato do cliente, a quantidade de vagas desejadas, a posição na fila (sequencial, atribuída no momento do registro) e o status atual (Aguardando, Notificado, Expirado, Cancelado ou Convertido). É a forma oficial de não perder demanda quando o estoque acabou e de organizar a ordem de prioridade quando vagas abrirem.

O administrador chega nesta página por dois motivos principais: para cadastrar manualmente alguém que ligou ou apareceu pedindo vaga em uma excursão lotada, ou para acompanhar a fila que se forma pelo site público (formulário do cliente final). Quando o sistema detecta que vagas voltaram a ficar disponíveis, ele percorre a fila por posição e envia uma oferta por e-mail com link de resgate; as vagas ficam retidas pelo período da oferta para evitar que outro cliente compre na frente.

Como usar

1. Vá em Viagens (Excursões) no sidebar, abra a excursão desejada e clique em Lista de Espera na navegação interna. A URL fica /admin/excursoes/{excursao}/lista-espera.

2. Confira os cinco cards de estatísticas no topo:

   • Aguardando - interessados aguardando vaga, em ordem de posição.
   • Notificados - receberam oferta e o link de resgate está dentro do prazo.
   • Convertidos - viraram passageiros (compra concluída).
   • Vagas retidas - total de vagas bloqueadas no estoque para sustentar as ofertas ativas. Só aparece quando há retenção.
   • Total - todas as entradas, em qualquer status.

3. Filtre a fila pela barra de filtros:

   • Buscar por nome, e-mail ou celular - texto livre.
   • Todos os status - Aguardando, Notificado, Expirado, Cancelado ou Convertido.

4. Cadastre alguém clicando em Adicionar (botão azul, canto superior direito). O modal abre com duas abas:

   • Buscar cliente - digite ao menos 2 caracteres por nome, CPF, e-mail ou celular. O sistema busca na base e já marca em vermelho quem Já está na lista de espera ou Já é passageiro dessa excursão (linha fica desabilitada). Clique no cliente para preencher os dados automaticamente.
   • Novo cadastro - preencha Nome completo, E-mail, CPF (opcional) e Celular manualmente.

5. Preencha os campos comuns às duas abas:

   • Quantidade de vagas - 1 a 10. O sistema só notifica este interessado quando houver pelo menos essa quantidade disponível ao mesmo tempo.
   • Observações - texto curto, opcional, visível só internamente.

6. Confirme em Adicionar à lista. O botão fica desabilitado enquanto houver conflito (já na lista ou já passageiro) ou enquanto o envio estiver em andamento.

7. Quando uma vaga abre (passageiro cancelado, capacidade aumentada), o próximo da fila com quantidade compatível é promovido a Notificado, recebe e-mail com o link de resgate (/lista-espera/claim/{token}) e a vaga fica retida até a expiração. Para forçar o envio antes do automático, use o menu de ações da linha Aguardando e clique em Enviar oferta.

8. Para uma entrada Notificado, abra o menu de ações e use:

   • Copiar link de resgate - copia o link público de claim para enviar manualmente (WhatsApp, ligação) caso o e-mail não chegue.
   • Converter em Passageiro - abre a tela de passageiros já com a conversão preenchida (?converter_le={entry_id}), útil quando o cliente confirmou por outro canal.
   • Cancelar oferta - desfaz a oferta, libera a vaga retida e marca a entrada como Cancelada.

9. Para uma entrada Aguardando que desistiu, use Remover da lista no menu de ações.

Casos especiais

Adicionando alguém que já está na lista ou que já é passageiro

O modal de cadastro consulta o endpoint verificar em tempo real (em lote, para o resultado da busca, e individual, ao selecionar o cliente). Se houver conflito, o card do cliente aparece com badge vermelho ("Já na lista de espera" ou "Já é passageiro") e o clique fica bloqueado. Mesmo assim, se a tentativa chegar ao backend, o controller recusa com toast "Este e-mail já está na lista de espera desta excursão." ou "Esta pessoa já é passageiro desta excursão.".

Cliente que quer mais vagas do que abriu

O job de processamento de vagas (processarVagasAbertas) pula quem está pedindo quantidade maior do que o número de vagas disponíveis no momento e continua para o próximo da fila com quantidade compatível. Resultado: alguém na posição 3 pedindo 1 vaga pode ser notificado antes de quem está na posição 1 pedindo 4 vagas. Para forçar a notificação manualmente, use Enviar oferta na linha desejada.

Oferta expirou sem o cliente comprar

Quando o prazo de horas_expiracao_oferta (24h por padrão, configurável em Jornada do Cliente > Lista de Espera) vence sem resgate, o cron expirarOfertas muda o status para Expirado, libera a vaga retida e reprocessa a fila - o próximo da fila com quantidade compatível recebe nova oferta automaticamente.

Conversão pelo cliente vs. conversão pelo admin

Quando o cliente clica no link de resgate e completa a compra pelo site, a entrada é marcada como Convertido automaticamente, com convertido_order_id apontando para a Order gerada. Quando o admin prefere lançar a venda na mão (cliente pagou no balcão, transferência manual), use Converter em Passageiro no menu de ações da linha - o sistema leva para a tela de passageiros com a conversão preparada.

Entrada cadastrada pelo admin vs. pelo site

Cadastros vindos do site público têm origem = 'site'. Os cadastrados pelo admin recebem origem = 'admin' e ganham o badge roxo Admin ao lado do nome, com tooltip mostrando quem adicionou.

Lista vazia

Quando ainda não há ninguém na fila, a tela mostra o ícone de fila com a mensagem "Nenhuma pessoa na lista de espera" e um atalho Adicionar manualmente que abre o mesmo modal de cadastro. O texto explica que, quando a excursão esgotar, os clientes poderão se inscrever sozinhos pelo site.

Erros comuns e como resolver

• "Este e-mail já está na lista de espera desta excursão." - Causa: já existe entrada com mesmo e-mail e status Aguardando ou Notificado. Solução: filtre por Aguardando ou Notificado e procure pelo e-mail; se for desistência antiga, remova a entrada anterior antes de cadastrar de novo.

• "Esta pessoa já é passageiro desta excursão." - Causa: o e-mail ou o cliente_id informado já tem passageiro com status confirmado ou pendente nesta excursão. Solução: confirme no módulo Passageiros se já não está cadastrado; se for outro membro do mesmo cadastro, use um e-mail próprio do interessado.

• "Esta entrada não está aguardando." (toast vermelho ao clicar em Enviar oferta) - Causa: a entrada já foi notificada, expirou, cancelada ou convertida. Solução: só entradas com status Aguardando podem ser ofertadas manualmente; para reenviar oferta expirada, cancele a antiga e cadastre de novo, ou aguarde o reprocessamento da fila.

• Cliente diz que recebeu a oferta mas o link "não funciona" - Causa: a oferta expirou no prazo configurado (24h por padrão) ou foi cancelada por outro operador. Solução: confirme o status atual na lista; se ainda for Notificado dentro do prazo, use Copiar link de resgate e reenvie manualmente.

Onde encontrar

• URL: /admin/excursoes/{excursao}/lista-espera
• Caminho no menu: Viagens (Excursões) > abrir a excursão > Lista de Espera
• Permissão necessária: ver as viagens (listar), editar as viagens (adicionar, notificar, cancelar), excluir as viagens (excluir permanentemente)
• Módulo necessário: nenhum (núcleo do produto)

Veja também

• Gerenciar Passageiros
• Excursões - Visão Geral
• Checklist de Embarque