Como Converter JSON para CSV Sem Perder Dados

Converter JSON para CSV é pegar um array de objetos e transformar cada objeto numa linha de planilha, com as chaves virando cabeçalhos de coluna. A parte que realmente confunde não é essa conversão básica, é o escaping: o que acontece quando um valor tem vírgula, aspas ou quebra de linha dentro dele. Errar essa regra é o motivo mais comum de um CSV “correto” abrir quebrado no Excel ou no Google Sheets.

Por que CSV ainda importa

JSON é o formato natural para APIs e para troca de dados entre sistemas, mas quase ninguém abre um .json numa planilha para analisar, filtrar ou montar um gráfico. CSV continua sendo o formato universal de entrada para Excel, Google Sheets, ferramentas de BI e pipelines de ETL que esperam texto tabular simples. Exportar um endpoint de API, um relatório gerado em JSON ou o resultado de uma consulta a um banco de dados como CSV é, na prática, o passo que separa “dado bruto” de “dado que alguém do time financeiro ou de operações consegue abrir e usar sem precisar de um programador do lado”.

O problema é que a conversão parece trivial até você encontrar um valor com vírgula dentro, um objeto aninhado ou um array. É aí que a maioria dos conversores caseiros (um .join(',') rápido escrito às pressas) quebra.

Como funciona a conversão, com um exemplo verificado

Pegue este JSON de exemplo, um catálogo pequeno de produtos:

[
  { "sku": "A100", "product": "Wireless Mouse, Black", "price": 19.99, "in_stock": true },
  { "sku": "A101", "product": "17\" Laptop Stand", "price": 42.5, "in_stock": false },
  { "sku": "A102", "product": "USB-C Cable", "price": 8.99, "in_stock": true }
]

O resultado correto em CSV é este:

sku,product,price,in_stock
A100,"Wireless Mouse, Black",19.99,true
A101,"17"" Laptop Stand",42.5,false
A102,USB-C Cable,8.99,true

Os cabeçalhos (sku,product,price,in_stock) vêm da união das chaves de todos os objetos do array, na ordem em que cada chave aparece pela primeira vez. Isso importa porque alguns conversores mais simples olham só para o primeiro objeto do array e descartam silenciosamente qualquer campo extra que apareça só a partir do segundo ou terceiro objeto. Se o seu segundo produto tivesse um campo discount que o primeiro não tem, um conversor ingênuo simplesmente perderia essa coluna. A regra correta é somar as chaves de todos os objetos.

Agora repare linha por linha no que aconteceu com o escaping:

A primeira linha de dados tem o valor Wireless Mouse, Black, que contém uma vírgula. Como o delimitador do CSV também é vírgula, esse valor precisa ser diferenciado do separador de colunas, então ele é envolvido em aspas duplas: "Wireless Mouse, Black". Sem isso, um leitor de CSV interpretaria a vírgula do meio do nome do produto como se fosse uma nova coluna começando, e a linha inteira desalinharia.

A segunda linha tem 17" Laptop Stand, com um caractere de aspas duplas literal (a marca de polegada, 17 polegadas). Aqui entram duas regras ao mesmo tempo, e é o ponto que mais gera confusão: primeiro, toda aspas dupla dentro do valor é duplicada, virando ""; depois, o valor inteiro é envolvido num par externo de aspas, porque ele contém o caractere que precisa de escaping. O resultado final é "17"" Laptop Stand". Essa é a regra de escaping de aspas do RFC 4180, o padrão que define o formato CSV: quando um leitor de CSV bem implementado encontra "" dentro de um campo entre aspas, ele sabe que aquilo representa uma única aspas literal, não o fechamento do campo.

A terceira linha, USB-C Cable, não tem vírgula, aspas nem quebra de linha, então passa direto sem nenhum tratamento especial: USB-C Cable. É o caso comum, a maioria das strings do mundo real não precisa de escaping algum.

O mesmo raciocínio vale para chaves ausentes. Se um objeto do array não tiver uma das chaves que aparece em outro, a célula correspondente fica em branco, sem gerar erro. Por exemplo, se só o terceiro produto tivesse um campo warranty_months e os outros dois não, as duas primeiras linhas teriam a célula da coluna warranty_months simplesmente vazia, e a linha do terceiro produto viria preenchida.

Conversor JSON para CSV

Cole um array JSON de objetos abaixo e o conversor gera o CSV na hora, direto no navegador, sem enviar nada para um servidor. Se o JSON for inválido ou não for um array, a ferramenta mostra um erro em vez de travar.

Erros comuns

Objeto aninhado virando [object Object]. Esse é o jeito mais silencioso de perder dado numa conversão. Se um dos seus objetos tiver um campo aninhado, como { "sku": "A103", "address": { "city": "São Paulo", "zip": "01310-100" } }, o valor de address não vira o objeto inteiro na célula, ele vira literalmente o texto [object Object], porque a conversão transforma o valor em string e um objeto JavaScript convertido em string dessa forma não carrega suas propriedades. A correção é achatar a estrutura antes de converter: em vez de um campo address aninhado, use dois campos de nível superior, address_city e address_zip, cada um com seu valor direto.

Array virando uma célula só, separada por vírgula. Se um campo tiver um array como valor, por exemplo "tags": ["red", "blue"], ele não vira três colunas nem mantém colchetes. Ele é achatado numa única célula com os itens separados por vírgula: red,blue. E como essa string resultante agora tem uma vírgula dentro, a regra de escaping entra em ação e a célula fica entre aspas: "red,blue". O dado não se perde, mas fica concentrado numa coluna só, o que costuma pegar quem espera uma coluna por item da lista.

A armadilha do separador de lista no Excel. O CSV gerado usa vírgula como delimitador de coluna, sem opção de ponto e vírgula. Isso é o padrão internacional, mas em instalações do Excel configuradas para português do Brasil (ou outras regiões onde a vírgula é o separador decimal dos números, como em boa parte da Europa), o Excel espera ponto e vírgula como separador de lista por padrão. O sintoma é abrir o CSV e ver tudo despejado numa coluna A só, sem separação nenhuma. Duas formas de resolver: usar “Dados > Texto para Colunas” no Excel e escolher vírgula como delimitador manualmente, ou trocar o separador de lista da configuração regional do Windows de ponto e vírgula para vírgula. O Google Sheets, por outro lado, costuma detectar vírgula corretamente na importação sem esse ajuste.

Esquecer de envolver um único objeto em colchetes. A ferramenta espera um array de objetos, [ {...}, {...} ], mesmo que você só tenha um registro para converter. Colar apenas { "sku": "A100", "product": "Wireless Mouse" }, sem os colchetes externos, não é um array válido para essa conversão e gera erro. Basta envolver o objeto único num array de um elemento: [ { "sku": "A100", "product": "Wireless Mouse" } ].

Perguntas frequentes

Como o conversor decide quais colunas o CSV vai ter? Ele soma as chaves de todos os objetos do array, na ordem em que cada chave aparece pela primeira vez, não apenas as chaves do primeiro objeto. Se um objeto não tiver uma das chaves encontradas em outro, a célula correspondente fica vazia em vez de gerar erro.

Por que meu campo de endereço virou [object Object] no CSV? Porque o valor daquele campo é um objeto JSON aninhado, e a conversão para texto de um objeto aninhado produz literalmente essa string, sem suas propriedades internas. A correção é achatar a estrutura antes de converter, transformando address: { city, zip } em dois campos de nível superior, como address_city e address_zip.

O CSV usa vírgula ou ponto e vírgula como separador? Só vírgula, sem opção de troca. Se você abrir o arquivo num Excel configurado para português do Brasil e ver tudo numa coluna só, use “Dados > Texto para Colunas” escolhendo vírgula como delimitador, ou ajuste o separador de lista da configuração regional do sistema.

O que acontece se um valor do JSON tiver vírgula ou aspas dentro? O conversor envolve o valor inteiro em aspas duplas seguindo o padrão RFC 4180. Se o valor também tiver uma aspas dupla literal, cada ocorrência é duplicada (" vira "") antes de aplicar o par de aspas externo. Isso garante que qualquer leitor de CSV compatível com o padrão reconstrua o valor original corretamente.

Meus dados ficam armazenados em algum servidor durante a conversão? Não. A conversão roda inteiramente no navegador, em JavaScript. Nenhum dado colado na ferramenta é enviado para fora do seu dispositivo.