Passageiros - Documentos e Requisitos

O que é

Importante esclarecer antes de mais nada: a listagem /admin/excursoes/{excursao}/passageiros não tem uma aba ou modal "Documentos do Passageiro". Os documentos pessoais que costumam ser pedidos para viajar (RG, CPF, CNH, passaporte, certidão de nascimento) são gravados no perfil do cliente (ou no perfil do dependente, quando o passageiro é um dependente), porque essas informações acompanham a pessoa em todas as viagens dela - não só naquela excursão específica.

Existem três blocos diferentes onde isso aparece no admin, e cada um resolve um problema distinto:

• Documentos do Cliente - anexos digitalizados de RG/CPF/CNH/ passaporte/certidão, com status Pendente, Aprovado ou Reprovado. Vivem em cliente_documentos e podem ser enviados pelo cliente (no Portal) ou anexados pelo admin direto no perfil do cliente/dependente.
• Ficha Médica - tipo sanguíneo, alergias, medicamentos, plano de saúde, contato de emergência. Editada no card Ficha Médica do perfil do cliente (ou do dependente).
• Cadastros Personalizados - formulários customizados que a agência cria para coletar qualquer outra informação obrigatória (dados de visto, lista de bagagem, ficha de inscrição com perguntas livres, autorização de menor, dados para seguro). Cada schema é vinculado a uma ou mais entidades (excursao, cliente, reserva) e aparece exatamente onde foi configurado.

Você normalmente chega nestas telas quando um passageiro liga perguntando por que não consegue embarcar (faltou documento aprovado), quando precisa anexar manualmente o passaporte que o cliente mandou por WhatsApp, ou quando a agência quer padronizar uma ficha extra (intolerâncias, contato de emergência específico daquela viagem).

Como usar

1. Anexar um documento manualmente no perfil do cliente

1. Vá em Cadastros > Clientes no sidebar e abra o cliente correspondente, ou clique no nome do passageiro na listagem da excursão para chegar ao perfil dele.
2. Role até o card Documentos (ícone azul-cyan de folha).
3. Clique em Adicionar (canto superior direito do card).
4. No modal Adicionar Documento do Cliente, escolha:
   • Tipo de Documento - RG, CPF, CNH, Passaporte ou Certidão de Nascimento. A lista de tipos disponíveis sai da configuração Documentos do Passageiro em Jornada do Cliente.
   • Arquivo - JPG, PNG ou PDF, máximo 5 MB.
5. Clique em Enviar. O documento entra no perfil já com status Aprovado (porque foi o admin que anexou).

2. Anexar documento de um dependente

1. No mesmo perfil do cliente titular, role até o card Dependentes.
2. Na linha do dependente, clique no ícone Adicionar documento (folha com sinal de +, em cinza).
3. O modal já vem rotulado "Para: {nome do dependente}". Repita o passo 4 do procedimento anterior.

Esse fluxo cria um cliente_documentos com cliente_id do titular e dependente_id preenchido - por isso o documento aparece nos dois lugares: no card do dependente e na fila central.

3. Pedir para o passageiro enviar sozinho

1. Mande o link mágico do cliente (botão Gerar link mágico na linha do passageiro, dentro da listagem da excursão) ou o convite de cadastro.
2. O cliente entra no Portal sem precisar de senha e vê o card Documentos em Minha Conta > Documentos.
3. Ele faz o upload (RG, CPF, CNH, passaporte ou certidão).
4. O documento entra na fila central em Tarefas > Documentos Pendentes (/admin/clientes/documentos?status=pendente) com status Pendente, esperando aprovação manual.
5. No perfil do cliente, o card Documentos mostra um selo amarelo Aprovar que leva direto para a fila filtrada por esse cliente.

Detalhe da revisão: documentos enviados pelo cliente podem vir pré-analisados pelo Gemini (badge roxa IA com sugestão de aprovar/ reprovar dentro do modal). Veja a página Clientes - Documentos do Cliente para o fluxo completo de aprovação/reprovação.

4. Preencher a ficha médica

1. No perfil do cliente (ou no perfil do dependente), localize o card Ficha Médica (ícone rosa de coração).
2. Clique em Editar.
3. Preencha os campos relevantes:
   • Tipo sanguíneo - A+, A-, B+, B-, AB+, AB-, O+, O-.
   • Alergias - texto livre (até 2000 caracteres).
   • Medicamentos de uso contínuo - texto livre.
   • Condições médicas - diabetes, hipertensão, marcapasso, etc.
   • Restrições alimentares - vegetariano, intolerância a lactose.
   • Necessidades especiais - mobilidade reduzida, cadeira de rodas.
   • Plano de saúde + Número da carteirinha.
   • Contato de emergência - nome, parentesco, telefone.
4. Clique em Salvar Ficha Médica. A ficha fica vinculada à pessoa (não à excursão), então uma única ficha serve para todas as viagens futuras dela.

5. Configurar um requisito extra (Cadastro Personalizado)

Quando precisa pedir algo que o sistema não tem nativamente - dados de visto americano, lista de bagagem, formulário de saúde específico, ficha do menor desacompanhado - use Cadastros Personalizados:

1. Vá em Cadastros > Cadastros Personalizados e crie um schema novo (ou abra um existente).
2. Em Entidades vinculadas, escolha onde o formulário deve aparecer:
   • Excursão - registro único por excursão (ex: lista de bagagem padrão da viagem).
   • Cliente - registro por cliente (ex: dados de visto que servem para várias viagens dele).
   • Reserva - registro por passageiro/reserva (ex: ficha médica específica daquela excursão, autorização daquela viagem).
3. Em Locais de exibição, marque onde o bloco do schema vai aparecer (cliente_show no perfil do cliente, excursao_edit na aba Cadastros da excursão, reserva_show na página da reserva etc.).
4. Salve o schema com os campos desejados (texto, número, data, select, boolean, anexo).
5. A partir daí, no local configurado, surge o card do schema com o botão Novo para criar registros. Cada registro fica associado à entidade pai (excursão, cliente ou passageiro/reserva).

6. Ligar/desligar a obrigatoriedade global de documentos

1. Vá em Configurações > Jornada do Cliente.
2. Localize a seção Documentos do Passageiro.
3. Ajuste:
   • Obrigatório (sim/não) - define se o site exige documento para concluir reserva.
   • Tipos aceitos - combinação de RG, CPF, CNH, Passaporte e Certidão de Nascimento (o admin só vê esses tipos no modal de upload do perfil do cliente).
   • Momento de exigência - quando o sistema cobra (antes do embarque, no checkout, etc.).
4. Salve. A mudança vale globalmente para todas as excursões da sua empresa.

Casos especiais

Documento que vale para a viagem mas é específico da reserva

A tabela cliente_documentos não tem coluna passageiro_id ou excursao_id - o documento sempre é da pessoa, não da viagem. Se você precisa de um anexo "que vale só para esta reserva" (ex: voucher de hotel reservado pelo cliente, ficha de inscrição assinada para esta excursão), use:

• Cadastros Personalizados com entidade_vinculada = reserva e um campo do tipo arquivo, OU
• Documentos da Reserva (card próprio na página de detalhes da reserva, usado para nota fiscal, recibo, comprovante de pagamento e contrato - não é para RG/passaporte).

Passageiro estrangeiro sem CPF

O cliente pode ser cadastrado com Documento Estrangeiro (tipo passaporte/RNE/CRNM) nos campos documento_estrangeiro_* do perfil. Os anexos digitalizados desse passaporte vão no card Documentos normal, escolhendo o tipo Passaporte no modal de upload.

Menor de idade desacompanhado

Não há fluxo nativo de "autorização de viagem assinada em cartório". O caminho recomendado:

1. Cadastre o menor como dependente do responsável legal (ou como cliente próprio, se a agência preferir).
2. Anexe a Certidão de Nascimento pelo card de documentos do dependente.
3. Crie um Cadastro Personalizado chamado "Autorização de Viagem de Menor" vinculado à reserva, com um campo do tipo arquivo (PDF da autorização escaneada) e campos extras (cartório, data, reconhecimento de firma, nome e CPF de cada responsável).
4. No dia do embarque, o guia consulta o registro pela página da reserva.

Validação automática pela IA (Gemini)

Documentos enviados pelos clientes via Portal podem passar por análise automática do Gemini antes de chegar ao admin. Quando isso ocorre, o registro vem com validado_por_ia = true e o JSON ia_analise preenchido (decisão sugerida, confiança, observações). A aprovação final continua sendo manual na fila central - a IA é apoio, não decisão.

Apagar e pedir reenvio

Quando o documento foi aprovado mas estava errado:

1. Vá em Tarefas > Documentos Pendentes (/admin/clientes/documentos).
2. Encontre o documento (filtre pelo cliente).
3. Clique em Excluir (menu de 3 pontinhos). Isso remove o arquivo do storage e libera o cliente para enviar um novo no Portal.

Erros comuns e como resolver

• "O motivo da reprovação é obrigatório." - Você tentou reprovar sem preencher o motivo no modal. Escreva no mínimo 10 caracteres explicando o que está errado (foto embaçada, validade vencida, documento cortado).
• "O motivo deve ter pelo menos 10 caracteres." - Texto curto demais. Seja específico para o cliente saber o que ajustar.
• Modal de upload do dependente não mostra o tipo desejado (ex: CNH)
  • O tipo não está na lista tipos_aceitos da configuração de Documentos do Passageiro em Jornada do Cliente. Ajuste lá e o tipo passa a aparecer no modal.
• Botão Adicionar do card Documentos não envia o arquivo - Verifique se o arquivo está em JPG/PNG/PDF e abaixo de 5 MB. O limite é validado no server.
• Não acho a aba Documentos dentro da página de Passageiros da excursão - Ela não existe. Documentos pessoais ficam no perfil do cliente; clique no nome do passageiro para abrir o cliente e role até o card Documentos. Documentos administrativos da reserva (nota fiscal, contrato) ficam na página de detalhes da reserva.
• "Limite de 5 documentos atingido." - Esse erro só aparece na página de detalhes da reserva (documentos administrativos da reserva). Não se aplica a RG/CPF/passaporte, que ficam no perfil do cliente e não têm esse limite.
• Item "Documentos Pendentes" sumiu do sidebar - Só aparece quando há fila. Acesse direto por /admin/clientes/documentos se precisar ver os já aprovados ou reprovados.

Onde encontrar

• URL canônica da listagem de passageiros: /admin/excursoes/{excursao}/passageiros
• Perfil do cliente (onde o card Documentos e o card Ficha Médica existem): /admin/clientes/{cliente}
• Fila central de aprovação: /admin/clientes/documentos
• Configuração global: Configurações > Jornada do Cliente > Documentos do Passageiro
• Caminho no menu para anexar manualmente: Cadastros > Clientes > {cliente} ou clicar no nome do passageiro na listagem
• Caminho no menu para aprovar: Tarefas > Documentos Pendentes (só aparece quando há fila)
• Permissões necessárias: ver as viagens (para ver a listagem), editar os clientes (para anexar/aprovar/excluir documentos e editar ficha médica)
• Módulo necessário: nenhum (faz parte do core)

Veja também

• Clientes - Documentos do Cliente - fila central de aprovação/reprovação dos documentos que chegam pelo Portal.
• Cadastrar Passageiro - como o cliente/dependente vai parar na lista de passageiros.
• Convites e Links de Confirmação - mandar link mágico para o passageiro completar dados e anexar documentos sozinho.