Excursões - Pontos de Embarque

O que é

O cartão Pontos de Embarque fica dentro da edição da excursão e é onde você define cada local pelo qual a viagem passa - tanto na ida quanto na volta. Cada ponto guarda nome, endereço completo, cidade, estado, CEP, ponto de referência, data, hora de embarque e hora de retorno, e pode estar vinculado a um veículo específico quando a excursão tem mais de um transporte cadastrado.

Você normalmente chega aqui logo depois de criar a excursão e antes de montar a tabela de preços - afinal, a matriz de preços usa os embarques como linhas. O título do cartão mostra entre parênteses a quantidade total de pontos cadastrados, e cada item da lista exibe rapidamente quantos passageiros ativos já estão vinculados àquele ponto (pílula verde com o sufixo pax).

Como usar

1. Abra a excursão em Excursões no sidebar e role até o cartão Pontos de Embarque (ícone de mapa).
2. Clique em Adicionar (botão azul no canto superior direito do cartão). O modal Novo Ponto de Embarque é aberto.
3. Preencha os campos:
   • Nome do Local (obrigatório) - ex: Terminal Rodoviário de Campinas. Use o botão Buscar ao lado para reaproveitar um local cadastrado em outras excursões.
   • CEP (opcional) - ao digitar 8 dígitos o sistema busca automaticamente o endereço, preenche Endereço, marca o Estado e seleciona a Cidade correspondente.
   • Ponto de Referência (opcional) - texto livre tipo Próximo ao posto Ipiranga.
   • Estado (obrigatório) - selecione a UF; isso carrega a lista de cidades válidas.
   • Cidade (obrigatória) - selecione na lista carregada pelo estado.
   • Endereço - rua, número e bairro.
   • Data de Embarque (obrigatória) - deve estar entre um dia antes da data de início e um dia depois da data de fim da excursão.
   • Hora de Embarque - recomendado; aparece para o passageiro no site e organiza a saída.
   • Hora de Retorno - opcional, usado nas listas de check-out.
   • Disponível para (só aparece com mais de um transporte) - selecione um veículo específico ou deixe Todos os veículos para compartilhar o ponto entre eles.
4. Confirme em Adicionar (ou Salvar, ao editar). Um toast confirma a operação e o ponto entra na lista.

A lista mostra cada ponto com sua ordem (círculo verde numerado), nome, endereço, cidade/UF, referência, data e horários, mais a quantidade de passageiros ativos. Use o lápis para editar e a lixeira para remover.

Casos especiais

Reaproveitar um local de outra excursão

Dentro do modal de cadastro, clique em Buscar ao lado do campo Nome do Local. O modal Buscar Ponto de Embarque lista locais já utilizados em qualquer excursão da sua empresa, agrupando duplicatas pela combinação nome + cidade + UF e exibindo uma pílula Nx quando o mesmo local já foi usado mais de uma vez. Digite ao menos 2 caracteres para filtrar por nome, cidade, endereço ou CEP. Clique no item para colar os dados no formulário de cadastro.

Ocultar um local da lista de sugestões

Passe o mouse sobre um item no modal Buscar Ponto de Embarque e clique no ícone de olho cortado para esconder aquele grupo (nome + cidade + UF) das próximas buscas. A confirmação avisa que os pontos já vinculados a excursões existentes não são afetados - só a sugestão é suprimida.

Reordenar os pontos

Use as setas para cima/para baixo à esquerda de cada item para mover um ponto de posição. Para um salto direto, clique no círculo verde numerado e digite a nova posição; a ordem é persistida em segundo plano via POST /embarques/reorder.

Alterar datas em massa (ida e volta)

Quando há ao menos um embarque cadastrado, aparece o botão âmbar Alterar Datas no topo do cartão. No modal:

• Data de Ida define a nova data dos embarques cujo nome não contém a palavra volta.
• Data de Volta (opcional) define a nova data dos embarques cujo nome contém a palavra volta.

Embarques que cruzam a meia-noite (ex: um ponto inicia às 22h e o seguinte sai às 01h) recebem D+1 automaticamente - o sistema usa o primeiro embarque com horário como referência e soma um dia àqueles cujo horário caiu antes das 6h após uma saída noturna.

Excursão com vários veículos

Se a excursão tem mais de um transporte cadastrado, o campo Disponível para aparece no modal. Use-o para indicar que um ponto é exclusivo de um veículo (ex: a van faz coletas extras de bairro antes de encontrar o ônibus principal). Pontos compartilhados ficam com Todos os veículos.

Janela de data válida

A Data de Embarque deve cair entre data_inicio − 1 dia e data_fim + 1 dia da excursão. Os campos min/max do seletor de data já refletem esses limites. Se a data ficar fora, o save retorna o erro de validação descrito abaixo.

Erros comuns e como resolver

• "A data de embarque deve estar dentro do período da excursão." - Causa: data informada fora da janela data_inicio − 1 até data_fim + 1. Solução: ajuste a data de embarque ou primeiro altere as datas da excursão na aba de dados.
• "O estado é obrigatório." / "A cidade é obrigatória." / "A data de embarque é obrigatória." - Causa: campo obrigatório vazio. Solução: preencha o item destacado em vermelho.
• "Transporte não pertence a esta excursão" - Causa: o veículo selecionado foi removido ou está em outra excursão. Solução: recarregue a página e selecione um transporte válido (ou Todos os veículos).
• "Este ponto de embarque possui N passageiro(s) vinculado(s): ... Altere o embarque dos passageiros antes de remover." - Causa: tentativa de excluir um ponto com passageiros confirmados ou pendentes. Solução: transfira os passageiros para outro embarque pela aba de passageiros e tente novamente.
• "Este ponto de embarque possui preco vinculado ao passageiro "...". Altere o embarque do passageiro antes de remover." - Causa: existe um passageiro ativo cujo preço aponta para este embarque. Solução: troque o ponto desse passageiro na aba de passageiros antes de remover.
• "O passageiro "..." usa o embarque atual, mas não há preço cadastrado lá para a mesma categoria. Cadastre o preço no novo embarque antes de remover este." - Causa: o passageiro foi movido para outro embarque, mas a categoria dele não tem preço lá. Solução: cadastre o preço da categoria no embarque atual do passageiro e tente remover novamente.
• "Embarque não pertence a esta excursão" - Causa: tentativa de editar/excluir um embarque que pertence a outra excursão. Solução: recarregue a página da excursão correta.
• "CEP não encontrado" (badge no campo de CEP) - Causa: CEP não resolvido pelo serviço de busca. Solução: preencha o endereço, estado e cidade manualmente.

Onde encontrar

• URL: /admin/excursoes/{excursao}/embarques (cartão exposto também em /admin/excursoes/{excursao}/edit#card-embarques e no wizard de criação).
• Caminho no menu: Excursões > (abrir excursão) > Pontos de Embarque.
• Permissão necessária: ver as viagens para visualizar e editar as viagens para criar/editar/remover/reordenar (trava de acesso aplicado no grupo api/excursoes/{excursao}).
• Módulo necessário: nenhum.

Veja também

• Visão Geral das Excursões
• Gerenciar Transportes
• Tabela de Preços
• Gerenciar Passageiros
• Criar Excursão