Clientes - Visão Geral do Módulo

O que é

O módulo Clientes é o cadastro central de todas as pessoas e empresas que viajam com a agência. É a partir dele que se geram passageiros em excursões, oportunidades no CRM, contratos digitais, cobranças, vouchers e acessos ao portal Minha Conta. Toda informação que se repete viagem após viagem - nome, CPF/CNPJ, documentos, ficha médica, dependentes, endereço, contato de emergência - vive aqui.

Você normalmente chega a este módulo logo no início da operação (para importar a base atual ou cadastrar os primeiros viajantes) e volta diariamente para confirmar dados antes de uma reserva, validar documentos, dar suporte ao cliente assumindo o perfil dele, mesclar duplicatas e acompanhar a ficha completa do viajante.

Como usar

Comece sempre pela listagem em Cadastros > Clientes no menu lateral. A partir dela você acessa todas as funcionalidades do módulo:

1. Vá em Cadastros > Clientes no menu lateral.
2. Use a barra de busca e os filtros (status, bloqueio, tags) para localizar um cliente - a busca também encontra clientes pelo nome ou CPF de um dependente.
3. Para um novo cadastro manual, clique em Novo Cliente no canto superior direito. Para migrar uma base inteira, use o Dropdown Ações > Importar Excel.
4. Clique no nome de um cliente para abrir o perfil 360, com dados pessoais, endereço, ficha médica, dependentes, documentos, viagens e - quando o módulo CRM está ativo - oportunidades, interações e tarefas.
5. Use o menu de 3 pontinhos em cada linha (ou as Ações Rápidas no perfil) para acessar como cliente, editar, ativar/desativar, bloquear/desbloquear, enviar e-mail de redefinição de senha, mesclar cadastro ou excluir.

Funcionalidades do módulo

Cada bloco abaixo é uma tela do módulo com artigo dedicado.

Listagem e busca

Página /admin/clientes com paginação de 10 em 10, busca por nome, e-mail, CPF, telefone, celular e por dados de dependentes. Filtros por status (ativo/inativo), bloqueio e por Tags. Detecção automática de possíveis duplicatas na primeira página sem filtros. Veja Clientes - Listagem.

Cadastro manual (PF e PJ)

Formulário /admin/clientes/create com:

• Pessoa Física com validação de CPF e checagem de duplicidade em tempo real.
• Pessoa Jurídica com lookup de CNPJ via Receita (preenche razão social, data de abertura, endereço e contato).
• Cliente estrangeiro com Passaporte ou DNI e Órgão Emissor.
• Verificação de e-mail e celular contra duplicidade.
• Verificação extra do número via Evolution API quando o módulo WhatsApp está ativo.
• Toggle Enviar email para definir senha que cria a conta do portal e dispara o e-mail.
• Três ações de salvar: Cadastrar Cliente, Cadastrar e continuar editando e Cadastrar e adicionar outro.

Veja Clientes - Cadastrar Cliente.

Perfil 360 do cliente

Página /admin/clientes/{cliente} que reúne em uma tela: dados pessoais, endereço, contato de emergência, ficha médica, lista de excursões (próximas e anteriores, com filtro por status da reserva), dependentes, documentos, contratos digitais e - com módulo CRM - oportunidades, interações e tarefas. Inclui card lateral com status, badges e Ações Rápidas. Veja Clientes - Perfil do Cliente.

Edição

Página /admin/clientes/{cliente}/edit com os mesmos campos do cadastro, mais o bloco de Contato de Emergência, Ficha Médica e Tags (sincronização requer permissão de ver as etiquetas). Alterações de nome, CPF, e-mail, celular e data de nascimento são propagadas automaticamente para os passageiros titulares ativos do cliente. Veja Clientes - Editar.

Dependentes

Cada cliente pode ter dependentes (filhos, cônjuge, outros). Dependentes têm cadastro próprio com nome, CPF, RG, data de nascimento, parentesco, documentos individuais e ficha médica. A busca da listagem encontra o cliente pai a partir do nome ou CPF do dependente. Veja Clientes - Dependentes do Cliente.

Documentos

Upload de documentos do titular e de dependentes (RG, CPF, passaporte, contratos avulsos, etc.), com fluxo de aprovação/reprovação pela equipe e validação automatizada por IA. Disponível em /admin/clientes/documentos (central) e dentro do perfil de cada cliente. Veja Clientes - Documentos do Cliente.

Importação em lote

Página /admin/clientes-import com download de planilha modelo, preview com validação linha a linha (CPF, e-mail duplicado, formato) e processamento em background. Use para migrar de outro sistema. Veja Clientes - Importar.

Status e bloqueio

Toggles ativo/inativo e bloqueado/desbloqueado controlam o acesso do cliente ao portal. Inativo desliga o acesso temporariamente; bloqueado registra uma trava explícita. Veja Status e Bloqueio.

Acesso ao portal e verificação de e-mail

Cada cliente pode ter conta no portal Minha Conta para ver reservas, pagar saldos, baixar vouchers e assinar contratos. O e-mail pode ser verificado por link enviado pelo admin (botão Enviar email para definir senha no cadastro e nas Ações Rápidas do perfil). Veja Verificação de E-mail e Área do Cliente.

Acessar como Cliente (impersonate)

Botão roxo Acessar como Cliente disponível para clientes ativos, não bloqueados e com e-mail verificado. Abre o portal do cliente no ponto de vista dele para suporte sem precisar da senha. Aparece no cabeçalho do perfil e no menu de 3 pontinhos da listagem. Veja Clientes - Acessar como Cliente.

Mesclar duplicatas

Quando dois cadastros representam a mesma pessoa (CPF, e-mail ou celular repetidos), o botão âmbar Mesclar cadastro no perfil unifica os dados, transfere passageiros, documentos e dependentes para o cadastro principal e remove o duplicado. Requer permissão clientes.merge. A listagem mostra possíveis duplicatas na primeira página sem filtros, via ClienteMergeService::detectDuplicates.

Integração com o CRM

Quando o módulo CRM está ativo, cada cliente ganha um card lateral com Lead Score, status, vendedor responsável e fonte. Surgem três blocos extras no perfil: Oportunidades (com estatísticas de abertas, ganhas, perdidas e valor total), Últimas Interações e Tarefas Pendentes. Atalhos Nova Oportunidade e Registrar Interação aparecem nas Ações Rápidas. Veja Clientes - Integração com CRM e Oportunidades.

Cashback, Milhagem e Preferências (modo Jornadas)

empresas em modo Jornadas (boutique) habilitam três blocos extras no perfil: lançamentos de Cashback (com saldo consolidado), Programas de Milhagem e Preferências de Viagem. Cada um tem permissão dedicada (clientes.cashback, clientes.milhagem, clientes.preferencias).

Tags

Cada cliente pode receber tags coloridas (do tipo cliente ou genéricas) para segmentar a base - grupos de viagem, perfil VIP, clientes corporativos, etc. As tags aparecem como filtro na listagem e exigem permissão de ver as etiquetas para edição.

Campos personalizados

O módulo respeita o CustomFieldService: cada empresa pode tornar campos obrigatórios (CPF, celular, data de nascimento, etc.) ou adicionar campos próprios via Configurações > Campos Personalizados. Validações de cadastro e edição se adaptam a essa configuração.

Sincronização automática com passageiros

Sempre que um cliente é atualizado, os passageiros titulares ativos dele (não cancelados, sem dependente_id) recebem os novos valores de nome, CPF, RG, e-mail, celular e data de nascimento. Isso mantém os manifestos e listas de embarque sempre alinhados com a ficha mestre, sem precisar editar passageiro por passageiro.

Endpoints AJAX de validação

Quatro rotas internas alimentam as validações em tempo real do formulário e podem ser usadas por integrações:

• GET /admin/api/check-cpf - valida algoritmo + duplicidade.
• GET /admin/api/check-email - duplicidade.
• GET /admin/api/check-phone - duplicidade por número limpo.
• GET /admin/api/check-whatsapp - checa via Evolution API se o número tem WhatsApp (somente com módulo ativo, com cache de 30 dias por cliente).

Casos especiais

empresa em modo Jornadas

Quando você opera no modo Jornadas (boutique) em vez de Excursões, o perfil substitui o bloco Excursões por Jornadas e adiciona os painéis de Cashback, Milhagem e Preferências na coluna lateral direita.

Cliente estrangeiro

Em qualquer formulário do módulo, basta escolher uma nacionalidade diferente de Brasileiro para que o CPF deixe de ser obrigatório e os campos Tipo de Documento (passaporte ou DNI), Número, Órgão Emissor e Data de Emissão apareçam.

Pessoa Jurídica

Cliente PJ tem bloco próprio Dados da Empresa com CNPJ, Razão Social, Inscrição Estadual, Inscrição Municipal e Data de Abertura. Ao salvar, os campos não aplicáveis ao tipo de pessoa são zerados automaticamente para evitar inconsistência (PF zera CNPJ/IE/IM; PJ zera CPF/RG/passaporte/data de nascimento).

Tags pessoais nas reservas

Quando o cliente é cadastrado dentro do fluxo de uma reserva (botão Novo Cliente no formulário de passageiros), o sistema usa as rotas excursoes/{excursao}/passageiros/cliente-rapido e cria o cliente já vinculado à reserva, sem passar pela listagem central.

Erros comuns e como resolver

• "Você não tem permissão para acessar Clientes" - A permissão de ver os clientes não está no perfil do usuário. Ajuste em Configurações > Perfis e Permissões.
• Cliente não aparece após cadastrar - Há filtros ativos (status, tag, bloqueio). Limpe os filtros no banner amarelo no topo da listagem.
• Botão "Acessar como Cliente" não aparece - Cliente está inativo, bloqueado ou sem e-mail verificado. Veja o card lateral direito no perfil para descobrir qual condição falta.
• Bloco CRM (Oportunidades, Interações, Tarefas) não aparece no perfil - Módulo crm não está ativo na sua empresa. Ative em Billing > Módulos.
• "Já existe um cliente com este e-mail/CPF/celular" - Detectado pelas rotas AJAX. Clique em Verificar cliente / Editar cliente existente no banner para abrir o cadastro original em vez de criar duplicata.
• WhatsApp marca número como inválido - Apenas informativo: o cliente é salvo, mas notificações automáticas via WhatsApp não serão entregues a esse número. Revalide manualmente quando o cliente trocar de chip.
• Possíveis duplicatas não aparecem mais - A detecção só roda na primeira página da listagem sem filtros. Tire os filtros e volte para a página 1.

Onde encontrar

• URL: /admin/clientes
• Caminho no menu: Cadastros > Clientes
• Permissão base: ver os clientes
• Permissões correlatas: criar os clientes, editar os clientes, excluir os clientes, clientes.merge, clientes.primeiro_acesso, clientes.cashback, clientes.milhagem, clientes.preferencias
• Módulo necessário: nenhum (recursos extras com CRM e WhatsApp)

Veja também

• Clientes - Listagem
• Clientes - Cadastrar Cliente
• Clientes - Perfil do Cliente
• Clientes - Editar
• Clientes - Importar
• Clientes - Acessar como Cliente
• Clientes - Dependentes do Cliente
• Clientes - Documentos do Cliente
• Clientes - Integração com CRM e Oportunidades
• Clientes - Área do Cliente (Portal Minha Conta)
• Status e Bloqueio
• Verificação de E-mail