Passageiros - Voucher e QR Code

O que é

O cartão de embarque (também chamado de voucher) é o comprovante que o passageiro apresenta no dia da viagem. Cada passageiro confirmado tem um qr_code único gerado automaticamente no cadastro, e esse código é o que o guia escaneia no check-in para liberar o embarque.

O cartão pode ser aberto como página HTML para o cliente acessar pelo celular, gerado em PDF (via Gotenberg, com fallback DomPDF) para impressão, e disparado por e-mail ou WhatsApp. Quando o passageiro tem dependentes ou faz parte de um grupo do mesmo comprador, o sistema reúne todos os cartões em uma única visualização de grupo, com um QR Code por passageiro.

Como usar

Abrir o cartão de embarque de um passageiro

1. Vá em Excursões no sidebar e abra a excursão desejada.
2. Acesse Passageiros na URL /admin/excursoes/{excursao}/passageiros.
3. Localize o passageiro na lista (use a busca por nome ou CPF, ou filtre por embarque).
4. Clique no botão de três pontinhos na linha do passageiro para abrir o dropdown de ações.
5. Clique em Cartão de Embarque (ícone de ticket). Abre em nova aba a página pública do cartão.
6. Na página pública, o passageiro vê o QR Code, dados da viagem e pode baixar o PDF ou abrir a versão impressa.

Quando o passageiro pertence a um grupo (titular com dependentes, ou várias compras do mesmo comprador na mesma excursão), o sistema detecta automaticamente e redireciona para a visualização de grupo (/embarque/{token}/grupo), exibindo um cartão por passageiro.

Enviar o cartão de embarque por e-mail

1. Vá em Excursões > Checklist ou abra a tela de check-in da excursão.
2. Clique no botão de envio do cartão de embarque ao lado do passageiro.
3. No modal Enviar Cartão de Embarque, clique em Enviar por E-mail (botão azul no topo).
4. O sistema dispara a CartaoEmbarqueNotification para o e-mail do cliente, registra em alertas_enviados e mostra mensagem de sucesso com o destinatário.

O botão fica desabilitado quando o cliente não tem e-mail cadastrado - o texto auxiliar mostra "E-mail não cadastrado".

Enviar o cartão de embarque por WhatsApp

1. Abra o mesmo modal Enviar Cartão de Embarque descrito acima.
2. Clique em Enviar por WhatsApp (botão verde abaixo do e-mail).
3. O sistema encurta a URL via ShortLink, monta a mensagem com dados da excursão e embarque, e enfileira EnviarWhatsAppJob usando o template viagilize_cartao_embarque quando o cliente estiver fora da janela de 24h.
4. A confirmação no modal mostra o telefone formatado para o qual a mensagem foi disparada.

Esse botão só aparece quando o módulo WhatsApp Mensagens está ativo e a instância está conectada (WhatsAppConfig::isConnected()). Sem o módulo, o modal mostra Compartilhar via WhatsApp, que abre wa.me com a mensagem pronta no celular do operador (sem disparo automático pelo servidor).

Reimprimir / reenviar

Não há limite de reenvios na interface. Cada disparo registra um AlertaEnviado com tipo = cartao_embarque. Para gerar um novo PDF a qualquer momento, basta abrir o Cartão de Embarque pelo dropdown - a URL com token é estável enquanto o passageiro não for cancelado.

Casos especiais

Envio automático programado

O cron embarque:enviar-cartao roda diariamente às 07:00 e usa CartaoEmbarqueService::enviarParaPassageiro(). Os gatilhos disponíveis (configurados em Configurações > Jornada do Cliente > Cartão de Embarque) são:

• reserva_criada - assim que a reserva entra
• pagamento_recebido - quando o passageiro quita
• apto_checkin - quando passa a estar aptoParaEmbarque() (default ativo)
• dias_antes - D-X (default 2 dias antes; configurável)
• dia_excursao - no dia da partida (default ativo)

Cada disparo automático respeita os canais selecionados em Jornada do Cliente (email/whatsapp) e o dedup por dia: jaEnviado() impede envio duplicado no mesmo dia para o mesmo passageiro.

Grupo (titular + dependentes ou várias compras do mesmo comprador)

Quando há mais de um passageiro vinculado ao mesmo comprador_id na excursão, o sistema usa gerarCartaoEmbarqueGrupo(), gera um PDF com uma página por passageiro reaproveitando o card _cartao-embarque-card.blade.php, e a mensagem de WhatsApp lista os nomes do grupo. O link enviado aponta para site.embarque.grupo.

Geração do PDF (Gotenberg vs DomPDF)

ContratoService::gerarCartaoEmbarque() tenta primeiro o Gotenberg (GotenbergPdfService::isAvailable()), renderizando pdf/gotenberg/cartao-embarque.blade.php com Tailwind via CDN. Se o Gotenberg não responder, cai para o DomPDF usando pdf/cartao-embarque.blade.php. O nome do arquivo é cartao-embarque-{qr_code}.pdf.

Passageiro cancelado ou transferido

Passageiros com status em cancelado ou transferido são pulados pelo envio automático e a página pública pode rejeitar o token. Reative o passageiro antes de tentar enviar novamente.

Erros comuns e como resolver

• "Passageiro não encontrado." - Causa: o passageiro_id informado não pertence à {excursao} da URL. Solução: abra o passageiro pela própria página de listagem da excursão correta.
• "Cliente não possui e-mail cadastrado." - Causa: o registro de cliente vinculado não tem email. Solução: edite o cliente em Clientes e cadastre o e-mail antes de reenviar.
• "Cliente não possui telefone cadastrado." - Causa: o cliente e o registro do passageiro estão sem telefone/celular. Solução: edite o cliente e adicione o número.
• "WhatsApp não está conectado ou módulo não está ativo." - Causa: módulo WhatsApp Mensagens desativado ou instância desconectada. Solução: ative o módulo em Módulos e reconecte em Configurações > WhatsApp.
• "Cartão de embarque não encontrado." - Causa: o token informado na URL pública expirou ou o passageiro foi cancelado. Solução: gere um novo cartão pelo dropdown Cartão de Embarque na lista de passageiros.

Onde encontrar

• URL: /admin/excursoes/{excursao}/passageiros
• Caminho no menu: Excursões > [abrir excursão] > Passageiros
• Permissão necessária: ver as viagens (para abrir o cartão e disparar e-mail/WhatsApp pelas rotas api.excursoes.passageiros.enviar-embarque-*)
• Módulo necessário: nenhum para gerar/visualizar; WhatsApp Mensagens para o disparo automatizado pelo servidor (sem o módulo, o botão Compartilhar via WhatsApp abre wa.me no celular do operador)

Veja também

• Passageiros - Check-in e Embarque
• Passageiros - Cadastrar Passageiro
• Passageiros - Status do Passageiro
• Passageiros - Visão Geral