O que é JSON (e por que tanta ferramenta pede isso)

Você abriu a ferramenta, configurou o formulário, chegou na etapa final e a tela pediu: “cole o JSON” ou “corpo da requisição”. Aí a mão parou. Não é falta de inteligência. É só um formato que a maior parte das pessoas nunca viu explicado com calma.

JSON aparece em API, webhook, exportação de CRM, automação no Make ou Zapier e em quase qualquer integração entre sistemas. Se você entende o “pacote” que essas ferramentas trocam, o resto fica menos misterioso. Este texto explica o que é JSON, como ler objetos e arrays, e como um pedido e uma resposta se parecem no dia a dia de uma PME.

JSON em uma frase

JSON (JavaScript Object Notation) é texto estruturado com chaves e valores que máquina e humano conseguem ler. Não é um programa. Não é um banco de dados. É um jeito padronizado de organizar informação para enviar, receber e guardar entre sistemas.

Imagine um envelope com etiquetas claras. Em vez de um parágrafo solto tipo “Maria pediu orçamento de site ontem”, o JSON deixa cada pedaço no seu lugar: nome, tipo de serviço, data, status. A ferramenta do outro lado não precisa “adivinhar” o que você quis dizer. Ela procura a chave certa e lê o valor.

Por isso tantas telas pedem JSON. Elas precisam de dados previsíveis. Se o formato estiver certo, a API processa. Se estiver torto, a integração falha, mesmo quando a ideia do negócio estava correta.

Se você ainda está se acostumando com a ideia de sistemas falando entre si, vale ler também o que é uma API no mesmo blog. JSON é, na prática, o idioma comum que muita API usa para o conteúdo da mensagem.

Objeto, array e tipos básicos

O bloco mais comum em JSON é o objeto. Ele fica entre chaves { } e guarda pares de nome e valor. O nome (a chave) vai entre aspas. Depois vem dois-pontos. Depois o valor.

Um objeto mínimo de lead pode ser assim:

{"nome":"Maria","email":"maria@empresa.com","origem":"site"}

Aqui há três campos. nome é texto. email também. origem também. Em JSON, texto (string) sempre vai entre aspas duplas.

Número não leva aspas:

{"quantidade":3,"valor":1500.5}

Verdadeiro ou falso (boolean) também não leva aspas:

{"ativo":true,"newsletter":false}

E null significa “sem valor” de propósito:

{"telefone":null}

Ou seja: string com aspas, número sem aspas, true/false sem aspas, null sem aspas. Misturar isso é uma das fontes clássicas de erro.

O array é uma lista. Fica entre colchetes [ ] e os itens são separados por vírgula. Serve quando há vários valores do mesmo tipo de informação.

{"servicos":["site","landing page","manutencao"]}

Você também pode ter uma lista de objetos. É o caso de vários itens de um pedido de orçamento:

{"itens":[{"nome":"Landing page","qtd":1},{"nome":"Formulario","qtd":1}]}

Leitura rápida: objeto = um “pacote” com campos nomeados. Array = uma “fila” de itens. Um JSON real mistura os dois o tempo todo.

Detalhe importante de sintaxe: entre um campo e outro, vírgula. No último campo do objeto (ou no último item do array), normalmente não vai vírgula. Comentários estilo // isso aqui não existem em JSON puro. Se alguém colar um trecho com comentário, o validador reclama.

Onde aparece no dia a dia

Na prática de quem opera ferramentas, JSON aparece em quatro lugares bem comuns.

Primeiro: corpo de uma chamada de API. Você envia dados (um lead, um pedido, um status) e a API responde com outro JSON confirmando ou devolvendo um identificador. O protocolo pode ser HTTP, o verbo pode ser POST, mas o conteúdo útil muitas vezes é JSON.

Segundo: webhook. Em vez de você perguntar o tempo todo “tem novidade?”, o sistema avisa quando algo acontece. Um formulário recebe um lead e dispara um webhook com o JSON daquele lead para o seu CRM, planilha ou automação. Se quiser o conceito sem tutorial longo, o post sobre webhook encaixa bem aqui: o webhook é o aviso, o JSON é o conteúdo do aviso.

Terceiro: exportação de ferramenta. CRM, e-commerce, helpdesk e formulários costumam oferecer export em JSON ou CSV. O CSV é tabela. O JSON costuma preservar melhor estruturas aninhadas (objeto dentro de objeto, lista de itens).

Quarto: o campo “data” (ou “body”, “payload”) em Make, Zapier e similares. A automação mostra um pacote de dados. Por baixo, aquilo quase sempre é JSON (ou vira JSON na hora de enviar para o próximo passo). Quando a tela pede para mapear nome ou email, você está escolhendo chaves daquele pacote.

Para uma PME, os exemplos são bem concretos. Pedido de orçamento no site vira um JSON com nome, empresa, telefone e tipo de serviço. Lead do formulário de “fale conosco” vira JSON com mensagem e origem da campanha. Atualização de status no pipeline (“novo”, “em contato”, “ganho”) também pode viajar em JSON entre formulário, planilha e CRM.

Você não precisa “programar JSON” no dia a dia. Precisa reconhecer a forma, achar o campo certo e corrigir o que quebrou a integração.

Pedido feito e resposta

Pense no fluxo completo: você manda um pedido e a ferramenta devolve uma resposta. Os dois lados costumam usar JSON.

Exemplo de pedido (o que você envia num POST, o “corpo da requisição”):

{"nome":"Maria","status":"novo"}

nome identifica a pessoa ou o contato. status diz em que etapa o lead ou o pedido está. Valores em texto ficam entre aspas. Não há vírgula depois do último campo.

A API processa e, se deu certo, pode responder com código HTTP 200 (sucesso) e um corpo assim:

{"id":"42","ok":true}

id é o identificador que o sistema criou para aquele registro. Você guarda esse id para consultar ou atualizar depois. ok confirma que a operação foi aceita. Aqui true não leva aspas porque é boolean, não texto.

Em um cenário de PME, o pedido pode ser um pouco mais completo, ainda sem complicação:

{"nome":"Maria","empresa":"Studio Norte","servico":"landing page","origem":"formulario-site"}

E a resposta pode trazer o mesmo espírito:

{"id":"42","ok":true,"status":"novo"}

O que importa no hábito de leitura: abra o pacote, localize as chaves, confira o tipo do valor. Se a ferramenta documenta “envie email como string”, não mande número. Se ela devolve ok como boolean, trate como verdadeiro/falso, não como a palavra "true" entre aspas (a menos que a documentação diga o contrário).

Quando a integração falha, olhe os dois JSONs. O de ida (o que você mandou) e o de volta (a mensagem de erro ou o corpo incompleto). Muitas vezes o problema não é “a API quebrou”. É um campo com nome diferente (e-mail vs email), um valor no formato errado, ou um array onde a ferramenta esperava um único objeto.

Erros comuns

Os erros de JSON são repetitivos. Isso é bom: depois que você vê três vezes, passa a achar rápido.

Vírgula a mais no final. Isto costuma quebrar:

{"nome":"Maria","status":"novo",}

A vírgula depois de "novo" é inválida na maior parte dos parsers. Remova a vírgula do último campo.

Aspas erradas. JSON padrão usa aspas duplas nas chaves e nas strings. Aspas simples ('Maria') ou aspas “bonitas” coladas do Word/Docs (“Maria”) geram erro. Reescreva com aspas retas duplas.

Copiar com comentário. Trechos de documentação às vezes vêm assim na cabeça da pessoa: chave, valor e um // obrigatório ao lado. JSON puro não aceita esse comentário. Cole só o objeto limpo.

Chave sem aspas. Em JavaScript solto às vezes funciona. Em JSON, não. Use "nome", não nome solto.

Número ou boolean entre aspas sem querer. "3" é texto. 3 é número. "true" é texto. true é boolean. Se a API valida tipo, essa diferença importa.

Array e objeto trocados. A ferramenta espera uma lista de itens [...] e você mandou um único objeto {...}, ou o contrário. Olhe a documentação ou um exemplo de resposta real da própria ferramenta.

Como validar sem drama: cole o texto em um validador JSON online confiável, ou use a pré-visualização da própria automação (Make/Zapier costumam mostrar se o JSON está inválido). Outra opção simples é colar no DevTools do navegador em contextos que aceitam parse, mas o validador dedicado já resolve o dia a dia. O objetivo não é ficar expert em sintaxe. É garantir que o pacote está bem formado antes de culpar a API.

Checklist rápido quando travar:

• O texto começa com { ou [ e fecha o par?
• Todas as chaves estão entre aspas duplas?
• Só há vírgula entre itens, nunca depois do último?
• Strings com aspas, números e boolean sem aspas?
• Não sobrou comentário nem texto explicativo no meio?

O que fazer agora

Abra um JSON real de uma ferramenta que você já usa. Pode ser o payload de um webhook de formulário, o corpo de exemplo na documentação da API do seu CRM, um export de pedidos, ou o pacote “data” de um cenário no Make/Zapier.

Em seguida, faça só isto:

1. Identifique três campos (por exemplo nome, email, status).
2. Diga o tipo de cada um (string, número, boolean, null, array ou objeto).
3. Reescreva mentalmente a frase de negócio: “isso é o lead da Maria, ainda novo, vindo do site”.

Se sobrar cinco minutos, altere de propósito um detalhe (vírgula a mais ou aspas tortas), rode no validador e veja a mensagem de erro. Depois corrija. Esse ciclo curto ensina mais do que qualquer glossário longo.

JSON não é moda de desenvolvedor. É o formato em que pedido de orçamento, lead de formulário e resposta de API viajam entre as ferramentas da sua operação. Quando a tela pedir “cole o JSON”, você já sabe o que está olhando: um pacote com chaves e valores, pronto para ser lido dos dois lados.