JSON

O que significa JSON?

JSON é a sigla de JavaScript Object Notation, ou Notação de Objetos JavaScript. Apesar do nome, ele não depende da linguagem JavaScript: praticamente todas as linguagens de programação, como Java, Python, PHP, C# e Go, conseguem ler e gerar JSON com facilidade.

Na prática, JSON é apenas texto organizado com algumas regras simples. Por isso, pode ser lido tanto por pessoas quanto por máquinas, o que o tornou o formato mais usado em APIs modernas.

Como é a estrutura de um JSON?

Um JSON é formado por objetos, delimitados por chaves, que contêm pares de nome e valor. Por exemplo: {"cnpj": "00000000000000", "valor_total": 150.00}. Cada nome vem entre aspas duplas, seguido de dois pontos e do valor.

Os valores podem ser textos, números, verdadeiro ou falso (true e false), nulo (null), listas entre colchetes ou outros objetos. Essa possibilidade de aninhar objetos permite representar estruturas complexas, como uma nota com emitente, destinatário e vários itens, cada um com seus próprios impostos.

Para que serve o JSON na emissão de notas fiscais?

Em uma API fiscal, o JSON costuma ser o formato usado para enviar os dados da venda ou do serviço e para receber as respostas. O ERP ou a plataforma de vendas monta um JSON com os dados da operação, como produtos, valores, CFOP, NCM e dados do cliente, e envia para a API.

A API valida essas informações, converte para o leiaute oficial exigido pela SEFAZ ou pela prefeitura, assina e transmite o documento. Depois, devolve em JSON o status da emissão, a chave de acesso, o protocolo ou o motivo de uma eventual rejeição, além de links ou conteúdos do XML e do PDF.

Isso permite que o sistema do cliente trabalhe com uma estrutura mais simples e uniforme, sem precisar lidar diretamente com os detalhes de cada leiaute de NF-e, NFC-e, NFS-e, CT-e ou MDF-e.

Qual a diferença entre JSON e XML?

Os dois são formatos de texto para representar dados, mas o XML usa marcações de abertura e fechamento, como <valor>150.00</valor>, enquanto o JSON usa chaves, colchetes e pares de nome e valor. Em geral, o JSON é mais curto e mais fácil de ler e manipular em aplicações web.

No mundo fiscal brasileiro, o documento oficial, como o XML da NF-e, continua sendo XML, pois é o formato definido nos leiautes e exigido para assinatura digital e guarda. O JSON aparece na camada de integração: é a forma como sistemas conversam com a API que cuida da emissão.

Quais erros são comuns ao trabalhar com JSON?

Os erros mais frequentes são de sintaxe: vírgula sobrando no último item, aspas simples no lugar de aspas duplas, chaves ou colchetes não fechados e caracteres especiais sem tratamento. Nesses casos, a API nem consegue ler a requisição.

Há também erros de conteúdo: o JSON está bem formado, mas um campo obrigatório ficou de fora, um número foi enviado como texto ou uma data está em formato diferente do esperado. Para evitar isso, muitas APIs publicam um JSON Schema ou uma documentação OpenAPI que descreve exatamente quais campos e tipos são aceitos.

Exemplos de JSON

• Um ERP envia para a API fiscal um JSON com os dados de uma venda, incluindo CNPJ do emitente, CPF do cliente, lista de itens com NCM e CFOP, e recebe de volta um JSON com o status da NF-e e a chave de acesso.
• Uma plataforma de serviços monta um JSON com o código do serviço, o valor e os dados do tomador para solicitar a emissão de uma NFS-e, sem precisar conhecer o leiaute exigido por cada município.
• Um webhook notifica o sistema do cliente com um JSON informando que uma NFC-e foi rejeitada, trazendo o código e o motivo da rejeição para correção.
• Um agente de inteligência artificial conectado via MCP consulta o status de documentos fiscais e recebe as respostas estruturadas em JSON.