1. O Conceito Básico: O que é JSON?

Para quem não é da área técnica, o nome pode assustar, mas o conceito é muito simples. Sempre que um sistema parceiro se comunica com o nosso, ele envia as informações compactadas em um formato de texto chamado JSON.

Imagine o JSON como uma ficha de cadastro básica, onde cada informação possui um rótulo (uma "chave") e um conteúdo (um "valor").

• Exemplo de como a informação chega:

• nome_cliente: Carlos Silva

• status_venda: payment_approved

Anteriormente, era necessário decifrar esse arquivo de texto. Hoje, o sistema faz isso de forma 100% automática. Ele lê o arquivo e gera uma lista pronta de opções fáceis para você clicar e selecionar na tela, como cliente.nome ou transacao.status.

2. O Primeiro Passo: Entendendo o Mapeamento de Dados

Mapear dados significa associar caminhos. É o ato de dizer ao sistema: "Pegue a informação que está chegando da plataforma externa (Origem) e guarde nesta gaveta específica dentro do nosso sistema (Destino)".

3. O que é Modelagem de Dados?

Depois que você já entendeu como mapear (levar o dado do ponto A ao ponto B), você pode utilizar a Modelagem de Dados. Ela serve para transformar o dado no meio do caminho.

Se a sua integração envia o e-mail do cliente com letras maiúsculas (CONTATO@EMAIL.COM), ou envia um status de pagamento em outro idioma (payment_pending), você pode aplicar funções automáticas para que o sistema corrija e limpe o dado antes de salvá-lo definitivamente na ficha do Lead.

4. Passo a passo para configurar

1. Acessar a aba de Integrações
No menu lateral esquerdo, acesse Funnel > Integrações. Por padrão, a tela abrirá na aba de webhooks. Localize e clique na integração desejada.

2. Adicionar um novo campo
Navegue até a seção de campos personalizados e clique no botão adicionar.

3. Configurar a origem, o destino e conferir o Preview
Preencha o campo Salvar em (Destino, onde a informação será guardada) e o campo Origem do valor (o dado mapeado que chega da integração).

Logo abaixo, o sistema exibirá uma área de Preview (Visualização) em tempo real. Use-a para confirmar se o sistema está capturando o dado correto antes de avançar.

#### 💡 Exemplo Prático: Mapeando para um Campo Personalizado

Se a sua operação precisa coletar um dado específico que não existe nativamente no sistema (como a data de aniversário do cliente), você realiza essa vinculação exatamente nesta etapa de preenchimento:

• Na coluna de destino (Salvar em), clique na seleção e role as opções para baixo até encontrar a categoria labels.personalizados.

• Juntamente à categoria, você verá listados todos os seus campos personalizados criados. Selecione a opção desejada (por exemplo: data_aniversario).

• Na coluna de origem (Origem do valor), selecione de qual campo da sua integração esse dado está vindo no JSON.

## O que é obrigatório mapear?

O mapeamento é totalmente opcional e sob demanda. Você só precisa mapear os dados que fizerem sentido para a sua estratégia. O sistema não exige o preenchimento de todos os campos que chegam.

A única regra obrigatória é para a criação do Lead: Para que o sistema consiga salvar qualquer informação, ele precisa primeiro registrar o contato no banco de dados. Portanto, você deve obrigatoriamente mapear pelo menos o e-mail OU o telefone do cliente. Os demais campos ficam ao seu critério.

Na lateral esquerda da tela principal da integração, o bloco "Campos obrigatórios mapeados para criar" (Lead, Transação, Logística e Empresa) serve apenas como um assistente visual para te orientar caso você queira utilizar alguma dessas entidades. Se você decidir gerar uma "Transação", por exemplo, ao clicar na aba correspondente em vermelho, um aviso em tela mostrará quais são os dados mínimos exigidos estritamente para aquela função.

4. Planejar Tratamento de Dados (Configurar Funções)
Caso o dado selecionado na sua origem precise de alguma modificação, formatação ou correção antes de ser salvo no destino final, clique no botão Configurar, localizado ao lado da opção de modelagem de dados. Na tela seguinte, clique em "Adicionar função" para escolher os tratamentos que deseja aplicar.

# Funções de Modelagem

Caso você utilize a etapa de tratamento (Item 4), use a lista abaixo para entender o que cada função faz:

Funções de Texto

• parseToString: Converte qualquer tipo de valor (como números) em texto comum. Exemplo: 12345 vira "12345".

• toLowerCase: Converte todas as letras para minúsculas (ideal para padronizar e-mails). Exemplo: Contato@Abc.com vira contato@abc.com.

• toUpperCase: Converte todas as letras para maiúsculas (útil para siglas e cupons). Exemplo: sp vira SP.

• trim: Remove espaços em branco invisíveis no início ou no final do texto. Exemplo: " Carlos " vira "Carlos".

• normalize: Remove acentos e caracteres especiais. Exemplo: João vira Joao.

• replace: Substitui um termo específico por outro de sua escolha. Exemplo: Trocar payment_pending por Aguardando Pagamento.

• prependText: Adiciona um texto fixo no início do valor recebido. Exemplo: Adicionar Ref:antes do número.

• appendText: Adiciona um texto fixo ao final do valor recebido. Exemplo: Adicionar - VIP ao final do nome.

Funções de Arrays (Listas)

• split: Divide um texto e cria uma lista usando um separador (como um espaço). Exemplo: Ana Clara vira ["Ana", "Clara"].

• getArrayFirst: Captura apenas o primeiro item de uma lista (útil para pegar o primeiro nome após o split). Exemplo: De ["Ana", "Clara"] pega apenas "Ana".

• getArrayLast: Captura apenas o último item de uma lista. Exemplo: De ["Ana", "Clara"] pega apenas "Clara".

• getArrayPos: Busca um item em uma posição numérica específica da lista.

• toArray: Transforma um valor comum em uma estrutura de lista.

• arrayToString: Junta os itens de uma lista em uma única linha de texto separada por vírgulas.

Funções de Números

• parseNumber: Transforma um texto em número real (obrigatório antes de fazer cálculos). Exemplo: "150.50" vira 150.5.

• add: Soma um valor fixo ao número recebido.

• subtract: Subtrai um valor fixo do número recebido.

• multiply: Multiplica o número recebido.

• divide: Divide o número recebido.

• round: Arredonda o número limitando as casas decimais. Exemplo: 99.9876 com 2 casas vira 99.99.

Funções de Datas

• parseDate: Altera o formato de exibição de uma data (organiza datas que chegam no padrão internacional para o padrão brasileiro). Exemplo: 2026-06-11 vira 11/06/2026.

Funções Lógicas e Condicionais

• returnIfExists: Se o dado existir, grava um texto personalizado; se estiver vazio, grava outro texto definido por você.

• exists: Grava um texto padrão apenas se a informação existir.

• notExists: Grava um texto padrão apenas se a informação estiver vazia ou ausente.

• existsInString: Verifica se o texto contém uma palavra específica e retorna um valor customizado se encontrar.

• stringLengthGreaterThan: Valida se o texto possui mais caracteres do que o limite definido.

Com esses passos, você consegue identificar corretamente os caminhos de origem e aplicar a modelagem de dados de forma precisa, garantindo informações organizadas, padronizadas e prontas para uso na sua operação.