Mapear campos para leads

Depois de criar o formulário, você precisa montar os campos (no builder visual) e mapear cada um Growth campo correspondente do lead — pra que name do form vire lead.name, email vire lead.email, e custom fields também sejam preenchidos. Esse artigo cobre os 11 tipos de campo, a lógica condicional, e a UI de mapeamento.

Pré-requisitos

• Formulário já criado. Veja Criar formulário.
• Permissão admin ou manager.

Acessar o builder

1. Em /formularios, clique no nome do form.
2. Página de edição abre. Clique em Builder no header (ou acesse /formularios/{form}/builder direto).
3. Builder mostra 3 painéis:

• Esquerda: sidebar com tipos de campo + (se multistep) seção Etapas.
• Centro: canvas com os campos arrastáveis.
• Direita: painel de configuração do campo selecionado (oculto até clicar campo).

Tipos de campo (11 disponíveis)

Clique no tipo no sidebar pra adicionar ao canvas. Cada tipo tem comportamento diferente:

💡 Dica: heading e divider são visuais apenas — não aparecem no envio/lead. Use pra organizar visualmente forms longos.

Telefone — bandeira e validação E.164

O campo tel usa intl-tel-input v25 com bandeira no input:

• Inicia mostrando bandeira do país padrão (configurável em Avançado, default BR).
• Máscara automática (formatAsYouType) — adapta conforme o país escolhido.
• Strict mode: bloqueia caracteres inválidos.
• Validação E.164 no submit — bloqueia número malformado.
• Salva como +5511999998888 no lead.

Países permitidos: configurável em Avançado (default: ~250 países). Veja Criar formulário — Configurações avançadas.

Configurar campo

Ao clicar num campo no canvas, painel direito abre com:

• Label (obrigatório): nome do campo (ex: "Nome completo", "Telefone").
• Tipo: dropdown pra mudar (cuidado: muda forma de validação).
• Placeholder (opcional): dica dentro do input (ex: "Digite seu e-mail").
• Texto de ajuda (opcional, max 500 chars): descrição abaixo do campo. Ex: "Vamos usar pra enviar atualizações.".
• Obrigatório (toggle): marca como required. Form bloqueia envio se vazio.
• Opções (só select/radio/checkbox): lista, uma por linha. Ex:

Pequena (até 10)
Média (11-50)
Grande (50+)

• Pertence à etapa (só multistep): dropdown de steps cadastrados.

Lógica condicional

Mostrar/esconder campo conforme outro campo tem valor X.

Como configurar

1. Clique no campo que deve aparecer condicionalmente (alvo).
2. No painel direito, marque Lógica condicional.
3. Apareça:

• Mostrar este campo quando:
• Campo origem (dropdown de outros campos do form).
• Operador: 5 opções (ver abaixo).
• Valor: input pra digitar valor (não obrigatório em not_empty/is_empty).

4. Salve.

Operadores disponíveis

Comparações são case-insensitive (não diferencia maiúsculas).

Exemplos práticos

Form de cadastro:

• Campo "Tipo de pessoa" (select: Física / Jurídica).
• Campo "CPF" só aparece se tipo = "Física".
• Campo "CNPJ" só aparece se tipo = "Jurídica".

Pesquisa NPS:

• Campo "Nota" (número 0-10).
• Campo "O que podemos melhorar?" só aparece se nota ≤ 6.

Diagnóstico:

• Campo "Setor" (select).
• Campos específicos do setor (ex: "Quantos quartos?" se setor = Imobiliária).

💡 Dica: lógica condicional não valida campos ocultos. Se um campo required tá oculto por condicional, o form aceita envio sem ele.

Salvar campos do builder

Botão Salvar e continuar no rodapé. Sistema:

1. Salva os fields (JSON) no Form.
2. Salva conditional_logic (array de regras).
3. Se multistep, salva steps (lista de etapas).
4. Redireciona pro mapeamento.

Mapear campos pra lead

Página /formularios/{form}/mapeamento abre com grid de 3 colunas: campo do form → seta → campo do CRM.

Campos do CRM disponíveis

Dropdown pra cada campo do form com opções:

Custom fields aparecem dinâmicos — todos os custom fields ativos do tenant. Formato: "Cidade (text)", "Receita anual (currency)". Veja Campos personalizados.

Como mapear

1. Pra cada linha (campo do form):

• Dropdown da direita lista as opções.
• Escolha o destino.

2. Salve.

Exemplo de mapping completo

Múltiplos campos pro mesmo destino

Se você mapeia 2 campos pro mesmo destino (ex: 2 campos pra "Nome"), o primeiro ganha. O segundo é ignorado pra esse destino, mas mantém valor no data JSON da submissão.

💡 Dica: campos sem mapeamento ainda são salvos no data JSON da FormSubmission. Aparece na listagem de envios, e exporta no CSV — só não preenche o lead. Útil pra perguntas internas ("Como nos conheceu?", "Aceita termos?").

Honeypot anti-spam

Cada formulário tem um campo invisível chamado _website_url que:

• É posicionado fora da tela (off-screen).
• Bots automáticos (que preenchem todos os campos) caem nele.
• Se chegou preenchido no servidor → submissão é bloqueada silenciosamente como spam.

Você não precisa configurar — vem ativo por padrão em todo form.

Ordem dos campos

Reorganize arrastando os campos no canvas. A ordem visual = ordem que o lead vê.

💡 Dica: coloque campos obrigatórios primeiro e os opcionais depois. Reduz abandono — user vê que é rápido (só 3 campos required) antes do "extra".

Validação no envio

Quando o lead clica Enviar:

1. Client-side (JS):

• Campos required preenchidos?
• E-mail tem @?
• Telefone E.164 válido?

2. Server-side (FormSubmissionService):

• Re-valida required (pula campos ocultos por conditional).
• Sanitiza valores (max length, regex).
• Cria lead via FormLeadCreator.
• Cria FormSubmission.
• Dispara post-actions (sequência, lista, task, e-mail notif).

Se validação falha:

• Mensagem de erro vermelha aparece abaixo do campo problemático.
• Form não é submetido.

Erros comuns

"Campo X é obrigatório" mesmo preenchido

Provavelmente está em conditional logic que oculta o campo dependente. Verifique se o campo origem está visível primeiro.

"Número inválido pro país"

Validação intl-tel-input rejeitou. Confira:

• País selecionado bate com o número (ex: bandeira BR + número americano falha).
• Quantidade de dígitos (Brasil = 10/11, EUA = 10).

"Mapeamento não está aplicando"

• Confira se você salvou o mapeamento (botão Salvar).
• Confira se o campo do form está mapeado pra algo válido (não "— Não mapear —").
• Para custom fields: confira se o CustomFieldDefinition está ativo (em /configuracoes/campos-extras).

Próximos passos

• Pra publicar no site, veja Embedar no site via SDK.
• Pra ver envios e leads gerados, veja Ver envios.

Artigos relacionados

• Criar formulário
• Tipos de formulário
• Embedar no site via SDK
• Campos personalizados
• Tags de contatos