Passeios - Criar Experiência

O que é

A página Nova Experiência é o ponto de entrada para cadastrar um passeio, experiência, aventura ou day use no catálogo da sua empresa. Ela usa um formulário único organizado em oito abas (Dados Gerais, Mídia, Localização, Categorias de Preço, Horários, Extras, Temporadas e SEO) e cria, em uma única transação, a experiência principal mais todos os relacionamentos: categorias de preço, horários recorrentes, extras e - automaticamente - as sessões futuras a partir dos horários cadastrados.

O usuário normalmente chega aqui pelo botão Nova Experiência dentro do catálogo (/admin/passeios), ao expandir o portfólio da agência ou ao publicar uma nova atividade sazonal. A página exige o módulo Passeios / Experiências ativo e a permissão de criar as experiências.

Como usar

1. Vá em Módulos > Passeios / Experiências > Catálogo no sidebar e clique em Nova Experiência (ou acesse direto /admin/passeios/create).
2. Na aba Dados Gerais, preencha os campos obrigatórios e operacionais:
   • Nome (obrigatório) - título principal exibido aos clientes.
   • Tipo - escolha entre Passeio, Experiência, Aventura ou Day Use.
   • Descrição Curta - resumo de até 500 caracteres usado em cards e listagens.
   • Descrição Completa - descrição rica do roteiro.
   • Duração (minutos), Dificuldade e Idade Mínima.
   • O que inclui / O que não inclui / O que levar / Requisitos - um item por linha.
   • Em Configurações, ajuste Antecedência mínima (horas), Cancelamento até (horas antes) e % Reembolso.
   • Toggles Ativo, Mostrar no site, Destaque e Permitir reagendamento.
   • Status: Rascunho, Publicado ou Arquivado.
   • Opcionalmente, configure os cards Exibição de Preços (sobrescreve o padrão global) e Seguro Viagem (link externo de seguradora parceira).
3. Na aba Mídia:
   • Faça upload da Imagem de Capa (JPEG, PNG ou WebP).
   • Escolha o Modo de Exibição do Banner: Padrão do Site, Hero, Vitrine, Split ou Minimal.
   • Em Vídeos do YouTube, clique em Adicionar Vídeo (até 5). Apenas URLs de youtube.com ou youtu.be são aceitas.
   • A Galeria de Fotos só aceita uploads depois que o cadastro for salvo pela primeira vez - aparece o aviso "Salve o cadastro primeiro para adicionar fotos à galeria.".
4. Na aba Localização:
   • Preencha Local/Destino, Endereço, País, Estado e Cidade. Para Brasil, o estado é um select de UFs e a cidade vem do autocomplete do IBGE. Para outros países, ambos viram texto livre.
   • Ponto de Encontro descreve o local do encontro em texto.
   • No mapa Leaflet/OpenStreetMap, busque o endereço ou clique diretamente para marcar a coordenada. O marcador é arrastável.
5. Na aba Categorias de Preço:
   • Defina o Modo de Preço: Fixo, Sob consulta ou Híbrido.
   • Clique em Adicionar Categoria e preencha Nome (ex: Adulto), Preço Custo, Preço Venda e Conta como (vagas).
   • Opcionalmente, vincule um Estoque de equipamentos (pool compartilhado) e defina Consome do estoque.
6. Na aba Horários:
   • Clique em Adicionar Horário e escolha o Tipo: Semanal, Diário ou Data Específica.
   • Para Semanal, marque os dias (Dom a Sáb). Para Data Específica, informe a data no calendário Flatpickr.
   • Preencha Início (obrigatório), Fim (opcional) e Vagas.
   • Ao salvar, o PasseioService::gerarSessoes() cria as sessões futuras automaticamente.
7. Na aba Extras, opcionalmente clique em Adicionar Extra para ofertas como foto profissional, refeição ou equipamento. Defina Nome, Preço e Cobrança (Por pessoa, Por reserva ou Por unidade).
8. Na aba Temporadas, opcionalmente cadastre períodos com ajuste de preço (alta temporada, feriados). Defina Nome, Datas, Tipo de Ajuste (Percentual ou Fixo), Valor do Ajuste (use negativo para desconto) e Prioridade (1-100, maior vence em sobreposição).
9. Na aba SEO, clique em Gerar com IA para popular Meta Title, Meta Description e Meta Keywords a partir dos dados já preenchidos (Gemini). O botão exige pelo menos o Nome preenchido.
10. Salve a experiência:
    • Criar Experiência - salva e volta para o catálogo.
    • Criar e continuar editando (no dropdown ao lado) - salva e abre a tela de edição, útil para subir as fotos da galeria.

Casos especiais

Modo "Sob consulta" (sem preço público)

Na aba Categorias de Preço, escolha o modo Sob consulta. O cliente no site vê "Valor sob consulta" e o CTA único leva ao formulário de cotação com a experiência pré-carregada. Mesmo assim, cadastre categorias de preço - elas continuam sendo usadas em orçamentos e em vendas feitas pelo admin.

Experiência sem horários recorrentes

A aba Horários pode ficar vazia: a tela mostra "Nenhum horário adicionado. Sessões serão geradas automaticamente a partir dos horários.". Sem horário cadastrado, o serviço não gera sessões e a experiência só poderá ser vendida via reservas manuais pelo admin ou via cotação.

Local internacional (fora do Brasil)

Quando o País é diferente de Brasil, os campos Estado/Província e Cidade viram texto livre (sem autocomplete IBGE). A busca no mapa usa o filtro countrycodes do Nominatim para o país selecionado, com fallback sem filtro caso não encontre.

Estoque compartilhado entre horários

Em cada categoria de preço, vincule um Estoque quando o passeio consome unidades de um pool finito (ex: 20 caiaques). O campo Consome do estoque define quantas unidades cada venda dessa categoria consome. Sem estoque vinculado, o limite é controlado apenas pelas vagas definidas no horário.

Galeria de fotos antes do primeiro save

A galeria só funciona depois que o passeio tem id. Use o botão Criar e continuar editando para já cair na tela de edição com a galeria disponível.

Erros comuns e como resolver

• "O campo nome é obrigatório." - Causa: a aba Dados Gerais ficou em branco. Solução: voltar para a aba Dados Gerais e preencher o Nome.
• "O campo categorias.0.nome é obrigatório." - Causa: você clicou em Adicionar Categoria mas não preencheu o nome. Solução: preencher o nome (ex: "Adulto") ou clicar em Remover na categoria vazia.
• "O campo horarios.0.horario_inicio é obrigatório." - Causa: horário adicionado sem hora de início. Solução: preencher Início no formato HH:MM ou remover o horário.
• "URL inválida. Use um link do YouTube (youtube.com ou youtu.be)." - Causa: aba Mídia recebeu uma URL que não casa com a regex do YouTube. Solução: usar link no formato https://youtu.be/XXXX ou https://www.youtube.com/watch?v=XXXX.
• "Endereço não encontrado. Tente ser mais específico ou usar o nome em outro idioma." - Causa: a busca no Nominatim não retornou resultados. Solução: incluir cidade no termo ou clicar manualmente no mapa.
• "Preencha o nome da experiência (aba Dados Gerais) antes de gerar o SEO." - Causa: clicou em Gerar com IA sem Nome. Solução: preencher o nome na aba Dados Gerais e voltar para a aba SEO.
• "Integração com IA não configurada." - Causa: chave do Gemini não configurada na sua empresa. Solução: pedir ao Proprietário para configurar a integração Gemini nas Configurações Gerais.
• "Erro ao cadastrar experiência: ..." - Causa: exceção durante a transação (ex: falha no banco, validação de relacionamento). Solução: o rollback é automático; o formulário volta com os dados preenchidos (withInput). Reveja a mensagem específica e tente novamente.

Onde encontrar

• URL: /admin/passeios/create
• Caminho no menu: Módulos > Passeios / Experiências > Catálogo > Nova Experiência
• Permissão necessária: criar as experiências (e ver as experiências para acessar o módulo)
• Módulo necessário: Passeios / Experiências (passeios-experiencias)

Veja também

• Passeios - Catálogo
• Passeios - Editar Experiência
• Passeios - Dashboard
• Passeios - Configurações do Módulo