Definição
Formato JSON é uma forma padronizada de organizar dados em texto, usando pares de nome e valor, listas e objetos, que pessoas e programas conseguem ler com facilidade. Em integrações fiscais por API, é o formato mais comum para enviar os dados de uma nota ao emissor e receber de volta status, mensagens e links.
Também conhecido como: JSON, JSON format, Notação JSON, Formato de dados JSON, JavaScript Object Notation
O que significa JSON e como ele é estruturado?
JSON é a sigla de JavaScript Object Notation, ou notação de objetos JavaScript. Apesar do nome, não depende da linguagem JavaScript. É um formato de texto simples que praticamente todas as linguagens de programação conseguem ler e gerar.
A estrutura usa poucos elementos. Objetos ficam entre chaves e reúnem pares de nome e valor, como {"numero": 150, "serie": "1"}. Listas ficam entre colchetes, como ["item A", "item B"]. Os valores podem ser texto entre aspas, números, verdadeiro ou falso (true e false), vazio (null), outros objetos ou outras listas.
Essa combinação permite representar informações complexas, como uma nota fiscal com emitente, destinatário, vários itens e seus impostos, de forma organizada e hierárquica.
Para que serve o formato JSON na emissão fiscal?
Em uma API fiscal, o JSON é a linguagem de conversa entre o sistema da empresa e o emissor. O ERP, a plataforma de vendas ou o marketplace monta um JSON com os dados da operação, como produtos, valores, CFOP e tributação, e envia esse conteúdo para a API.
A API valida os dados, converte as informações para o leiaute oficial exigido pela SEFAZ ou pela prefeitura e acompanha o processamento. Depois, responde também em JSON, informando o status do documento, a chave de acesso, o protocolo de autorização, mensagens de rejeição e os caminhos para baixar o XML e o PDF.
Assim, o desenvolvedor trabalha com uma estrutura moderna e legível, sem precisar montar manualmente o XML fiscal nem lidar diretamente com os web services de cada autorizador.
Qual a diferença entre JSON e XML nos documentos fiscais?
O XML é o formato oficial dos documentos fiscais eletrônicos brasileiros, como NF-e, NFC-e, CT-e e MDF-e. É o XML que recebe a assinatura digital, é transmitido ao órgão autorizador e tem validade jurídica, por isso deve ser guardado pela empresa.
O JSON, nesse contexto, é o formato de integração. Ele transporta os dados entre sistemas, mas não substitui o documento fiscal. Um JSON enviado para a API não é uma nota fiscal; ele é a matéria-prima a partir da qual a nota é gerada.
Na prática, os dois convivem: o sistema envia JSON, a API produz o XML oficial e devolve as respostas em JSON, com acesso ao XML autorizado.
Quais cuidados evitam erros ao enviar dados em JSON?
Respeitar os tipos de dados é o ponto principal. Campos como CNPJ, CPF, CEP e NCM devem ser enviados como texto, entre aspas, para não perder zeros à esquerda. Valores monetários e quantidades costumam ser números com ponto como separador decimal, nunca vírgula.
Também é importante usar a codificação UTF-8, para que acentos e caracteres especiais cheguem corretos, e informar no cabeçalho da requisição o tipo de conteúdo application/json. Datas normalmente seguem um padrão definido na documentação da API, geralmente com fuso horário explícito.
Muitas APIs descrevem a estrutura esperada com um JSON Schema ou uma especificação OpenAPI. Validar o conteúdo contra essas regras antes do envio reduz rejeições e erros de validação.
Por que o JSON virou padrão em APIs modernas?
O JSON é mais enxuto que formatos como XML, já que não repete etiquetas de abertura e fechamento. Isso gera mensagens menores e mais fáceis de ler, tanto para pessoas quanto para máquinas.
Ele também é o formato natural das APIs REST e é usado em protocolos mais recentes, como o MCP, que se baseia em mensagens JSON-RPC para permitir que agentes de inteligência artificial consultem documentos e executem ações autorizadas.
Exemplos de Formato JSON
- Uma plataforma de e-commerce envia à API fiscal um JSON com os dados do pedido, incluindo itens, NCM, valores e endereço do cliente, para emitir a NF-e da venda.
- Um software de gestão de clínicas monta um JSON com tomador, código do serviço e valor para emitir a NFS-e de uma consulta.
- Após o processamento, a API responde com um JSON contendo o status autorizado, a chave de acesso e os links para download do XML e do DANFE.
- Quando a SEFAZ rejeita uma nota, o sistema recebe um JSON com o código e o motivo da rejeição, que pode ser exibido ao usuário para correção.
Perguntas frequentes
Posso enviar a nota fiscal em JSON diretamente para a SEFAZ?
Não. A SEFAZ e as prefeituras exigem XML em leiautes oficiais e assinado digitalmente. O JSON é usado na comunicação com a API fiscal, que faz a conversão para XML, a assinatura e a transmissão ao órgão autorizador.
O JSON de envio precisa ser guardado como documento fiscal?
Não. O documento com validade jurídica é o XML autorizado. Guardar o JSON enviado pode ajudar em auditorias técnicas e investigação de erros, mas a obrigação de guarda recai sobre o XML fiscal.
Por que o CNPJ deve ir como texto no JSON?
Porque números não preservam zeros à esquerda. Um CNPJ ou CEP iniciado por zero, se enviado como número, perde esses dígitos e gera erro de validação. Enviando entre aspas, como texto, o valor chega exatamente como deve.
Atualizado em · Como produzimos este glossário