# Mapear o corpo recebido para campos do contato

> JSONPath na prática: o caminho de cada valor num JSON de exemplo, o tipo de campo certo e o que muda entre o webhook de entrada e o fluxo.

Endereço: https://docs.nextags.com.br/webhooks/mapear-campos/
Tipo: Guia

Atualizado em: 26/10/2026

Mapear é ligar cada valor de um JSON a um campo do contato, com um caminho JSONPath. Três lugares da NexTags fazem isso, cada um com as suas regras:

| Onde | De onde vem o JSON | Onde fica o caminho |
|---|---|---|
| Webhook de entrada | O corpo que o outro sistema manda | **Find or create contact** e **Save incoming data** |
| Requisição externa | A resposta da sua API | Aba **Mapeamento de resposta** |
| **Obter dados de JSON** | Um campo de texto do contato que guarda um JSON | **Salve a resposta em um campo personalizado.** |

Este guia usa um JSON de exemplo para mostrar o caminho de cada valor, o tipo de campo certo e o que muda em cada lugar.

**Antes de começar**

- Um exemplo real do JSON. Veja no passo 1 onde conseguir.
- Os campos personalizados que vão receber os valores. Veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/).

## Passo a passo

### Passo 1: Pegue um exemplo real do JSON

Monte os caminhos sobre um JSON de verdade, e não sobre a documentação de memória: um nome de chave diferente basta para o campo ficar vazio.

- **Webhook de entrada**: o histórico de envios da outra plataforma, como o **Payload** da Hotmart ou o **Ver logs** da Kiwify, ou um envio de teste para o Test URL do n8n. Veja [Exemplos de plataformas](https://docs.nextags.com.br/webhooks/exemplos-de-plataformas/).
- **Requisição externa**: o **Corpo da resposta**, no **Testar Agora** da ação.
- **Obter dados de JSON**: o conteúdo do campo. Para ver, mostre o campo numa mensagem de teste.

O exemplo deste guia, um pedido:

```json
{
  "cliente": {
    "nome": "Ana Souza",
    "email": "ana@exemplo.com.br",
    "telefone": "5511988776655",
    "vip": true
  },
  "pedido": {
    "id": "PED-1001",
    "numero": "000123",
    "total": 249.9,
    "pago_em": 1793030400,
    "itens": [
      { "produto": "Curso de Confeitaria", "preco": 199.9 },
      { "produto": "Apostila impressa", "preco": 50 }
    ]
  },
  "utm": { "utm_source": "instagram" },
  "dados-do-cupom": { "código": "BEMVINDO10" }
}
```

### Passo 2: Ache o caminho de cada valor

O caminho começa com `$`, o JSON inteiro, e desce um nível a cada ponto. Item de lista vai entre colchetes, contando do zero. Chave com hífen, espaço ou acento vai entre aspas e colchetes.

| Valor que você quer | JSONPath | Resultado |
|---|---|---|
| E-mail do cliente | `$.cliente.email` | `ana@exemplo.com.br` |
| Telefone do cliente | `$.cliente.telefone` | `5511988776655` |
| Cliente VIP | `$.cliente.vip` | `true` |
| ID do pedido | `$.pedido.id` | `PED-1001` |
| Número do pedido | `$.pedido.numero` | `000123` |
| Total do pedido | `$.pedido.total` | `249.9` |
| Data do pagamento | `$.pedido.pago_em` | `1793030400` |
| Primeiro produto | `$.pedido.itens[0].produto` | `Curso de Confeitaria` |
| Preço do segundo produto | `$.pedido.itens[1].preco` | `50` |
| Origem da campanha | `$.utm.utm_source` | `instagram` |
| Código do cupom | `$["dados-do-cupom"]["código"]` | `BEMVINDO10` |

```jsonpath
$.cliente.email
$.pedido.itens[0].produto
$["dados-do-cupom"]["código"]
```

O caminho precisa chegar num valor: um texto, um número, `true` ou `false`. `$.pedido` e `$.pedido.itens` apontam para um grupo de dados, e não para um valor. Para listas de tamanho que muda, só dá para pegar posições fixas, como `[0]` e `[1]`: se precisar de todos os itens num texto só, monte esse texto no sistema que manda o JSON.

### Passo 3: Escolha o tipo de campo

O tipo do campo personalizado decide o que dá para fazer com o valor depois, nas condições e nas mensagens.

| Valor | Tipo de campo | Por quê |
|---|---|---|
| Valores e quantidades, como `249.9` | Número | Dá para comparar nas condições, como "maior que". Mande o número com ponto, sem `R$`. |
| IDs e códigos, como `PED-1001` e `000123` | Texto | Um ID não entra em contas e pode ter letras e zeros à esquerda. Guarde como texto, mesmo quando só tem números. |
| Datas, como `1793030400` | Data, ou Data e hora | Os campos de data guardam a data em Unix timestamp, em segundos. Uma data em outro formato, como `2026-10-26T13:00:00-03:00`, guarde num campo de texto. |
| Verdadeiro ou falso, como `true` | Verdadeiro/Falso | O campo guarda `0` ou `1`. Confira no teste como o `true` e o `false` do seu JSON ficam. |
| Textos grandes, como uma descrição ou o JSON inteiro | Texto longo | É o tipo para textos grandes. **Obter dados de JSON** lê o JSON de campos de texto e de texto longo. |

Na API, o valor de um campo vem como texto quando o tipo é Texto (`0`) e como número nos outros tipos, como neste campo de número:

```json
{ "id": 3001, "name": "Valor do pedido", "type": 1, "value": 249.9 }
```

Os tipos e as variáveis estão em [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/).

### Passo 4: Mapeie no webhook de entrada

A tela do webhook de entrada aceita só três formas: `.chave`, `["chave"]` (ou `['chave']`) e `[n]`. Use `.chave` só para chaves com letras sem acento, números e `_`, que não comecem com número; qualquer outra chave vai entre aspas e colchetes.

```text
Aceitos                            Recusados
$.cliente.email                    $.pedido.itens[*].produto     (curinga)
$["dados-do-cupom"]["código"]      $..email                      (dois pontos seguidos)
$.pedido.itens[0].produto          $.pedido.itens[-1].produto    (índice negativo)
$['utm']['utm_source']             $.dados-do-cupom.código       (hífen e acento fora das aspas)
```

Os avisos que a tela mostra, em inglês:

| Aviso | O que quer dizer |
|---|---|
| `Start the path with $.` | O caminho não começa com `$`. |
| `Use .key, ["key"], or [0]. Filters and wildcards are not supported.` | Uma parte do caminho não está numa das três formas aceitas. |
| `Close the quoted key with ].` | Falta fechar as aspas ou o colchete de uma chave. |
| `Select a value rather than an object or array.` | O caminho chega num grupo de dados (objeto ou lista), e não num valor. |
| `No value found in sample data.` | O exemplo não tem esse caminho. Se o dado é opcional e só falta no exemplo, dá para salvar assim. |
| `Load sample JSON to preview this path.` | Ainda não há exemplo carregado: cole em **Sample JSON** e clique em **Load sample JSON**. |
| `Array index is too large.` | O número entre colchetes é grande demais. |

Ao salvar, os avisos de **Find or create contact** aparecem com o nome do campo na frente, como `Número de telefone: Start the path with $.`. Os caminhos de **Save incoming data** não são conferidos ao salvar: olhe o `Result:` de cada um antes.

### Passo 5: Mapeie no fluxo

Na requisição externa (**Mapeamento de resposta**) e em **Obter dados de JSON**, escreva o caminho do mesmo jeito: `$`, a chave depois de cada ponto e `[n]` para listas. Ao lado de **JSONPath**, na requisição externa, o ícone ⓘ abre um site que ajuda a achar o caminho num JSON colado.

Em **Obter dados de JSON**, escolha em **Dados JSON** o campo de texto que guarda o JSON e, embaixo, uma linha por valor, com o caminho e o campo que recebe (até 100 linhas). A ação tem duas saídas:

- **Sucesso**: pelo menos um campo foi preenchido.
- **Falhado**: o JSON é inválido ou nenhum campo foi preenchido.

```text
Dados JSON: o campo Resposta do pedido
$.pedido.id       → ID do pedido
$.pedido.total    → Valor do pedido
$.cliente.vip     → Cliente VIP
```

> **Um caminho errado apaga o valor do campo:**
> Em **Obter dados de JSON**, se o caminho de uma linha está errado, o valor que o campo tinha é apagado. Com vários campos na mesma ação, o contato pode sair por **Sucesso** com um campo perdido. Antes de usar o valor, confira numa etapa **Condição** se o campo tem valor. Veja [Etapa Condição](https://help.nextags.com.br/tutoriais/fluxos/condicoes/).

O passo a passo de tela está em [Obter dados de JSON](https://help.nextags.com.br/tutoriais/fluxos/dados-de-json/) e em [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/).

## Pronto: como conferir

- No webhook de entrada, cada caminho mostra `Result:` com o valor esperado, depois de **Load sample JSON**.
- Na requisição externa, o **Testar Agora** mostra o **Corpo da resposta**, e o caminho de cada linha bate com ele.
- Depois de um teste de verdade, os campos aparecem preenchidos no painel do contato, na **Caixa de Entrada**, com o tipo certo.

## Se não funcionou

### O campo ficou vazio

O caminho não achou o valor. Compare letra por letra com o JSON real, com maiúsculas e minúsculas, e confira o nível de cada chave. Um envio real pode não trazer um dado opcional.

### O campo perdeu o valor que tinha

Em **Obter dados de JSON**, um caminho errado apaga o valor anterior. Corrija o caminho e, nos campos importantes, confira o valor com uma condição antes de usar.

### O valor ficou diferente do JSON

Confira o tipo do campo: um texto como `PED-1001` não cabe num campo de número, e um valor com `R$` ou vírgula não é um número. Para datas, use um campo de data com Unix timestamp ou um campo de texto.

### A tela pede um valor, e não um objeto ou uma lista

O caminho para num grupo de dados. Desça até o valor, como `$.pedido.itens[0].produto` em vez de `$.pedido.itens`.

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Preciso mapear um JSON para campos de contato da NexTags. Leia este guia: https://docs.nextags.com.br/webhooks/mapear-campos.md

Onde vou mapear: [webhook de entrada / Mapeamento de resposta da requisição externa / Obter dados de JSON]. Este é o JSON, sem dados reais: [cole aqui]. Os dados que quero guardar: [liste]. Para cada um, me dê o JSONPath (no webhook de entrada, só com .chave, ["chave"] e [0]), o nome do campo personalizado e o tipo certo (Texto, Número, Data, Data e hora, Verdadeiro/Falso ou Texto longo).
```