Conversão CSV ↔ JSON explicada
CSV (Comma-Separated Values) e JSON (JavaScript Object Notation) são os dois formatos de dados mais comuns na web. Esta ferramenta converte entre eles de forma instantânea no próprio navegador.
CSV → JSON
A primeira linha do CSV é interpretada como cabeçalho (nome das chaves). Cada linha subsequente vira um objeto JSON. Campos entre aspas duplas são tratados corretamente, mesmo que contenham vírgulas ou quebras de linha internas.
JSON → CSV
O JSON de entrada deve ser um array de objetos com estrutura uniforme. As chaves do primeiro objeto viram o cabeçalho do CSV. Valores que contêm vírgulas são automaticamente envolvidos em aspas duplas para respeitar a especificação RFC 4180.
Casos de uso comuns
Exportações de planilhas (Excel, Google Sheets) para APIs REST, transformação de respostas de API para importação em banco de dados, e integração de dados entre sistemas com formatos distintos.
Quando usar e quando não usar
A situação mais comum no varejo é a lista semanal de ofertas: o comprador exporta a planilha, o encarte digital consome JSON. Aqui a conversão é imediata e dá para conferir a estrutura antes de entregar ao desenvolvedor. O caminho inverso também aparece bastante: pegar o array que uma API devolveu e transformar em CSV para abrir no Excel e filtrar.
A ferramenta não é para arquivos pesados. A conversão roda de novo a cada tecla digitada no campo, então milhares de linhas deixam a digitação lenta; para esse volume, converta com um script. Também não serve para JSON aninhado, com objetos dentro de objetos: o CSV é uma tabela plana, e esses campos não têm como virar coluna sem uma etapa de achatamento antes.
Exemplo: planilha de ofertas com separador brasileiro
Três colunas de preço com vírgula decimal e um nome de produto com aspas dentro, exportados com ponto e vírgula, como faz o Excel em português:
codigo;descricao;preco_de;preco_por
7891000100103;"Arroz Tipo 1 5kg";27,90;21,98
7896005800119;"Café Torrado ""Extra Forte"" 500g";19,49;15,99Com a opção Usar ponto e vírgula como separador marcada, a saída é:
[
{
"codigo": "7891000100103",
"descricao": "Arroz Tipo 1 5kg",
"preco_de": "27,90",
"preco_por": "21,98"
},
{
"codigo": "7896005800119",
"descricao": "Café Torrado \"Extra Forte\" 500g",
"preco_de": "19,49",
"preco_por": "15,99"
}
]As aspas duplicadas do CSV viraram uma aspa escapada no JSON, que é o comportamento correto. Os preços continuam texto, com vírgula. E com a opção desmarcada o resultado desanda: a linha de cabeçalho inteira vira o nome de uma única chave, e o valor é cortado na vírgula do primeiro preço, "7891000100103;Arroz Tipo 1 5kg;27". É o sintoma que o time costuma descrever como "a planilha virou uma coluna só".
Como a conversão funciona
No sentido CSV para JSON, um parser escrito para seguir a RFC 4180 lê o texto caractere por caractere, alternando entre "dentro de aspas" e "fora de aspas". Fora de aspas, o separador fecha o campo e a quebra de linha fecha o registro; dentro, ambos são texto comum, e duas aspas seguidas viram uma. O caractere de retorno de carro é descartado, então arquivos gerados no Windows funcionam. A primeira linha dá os nomes das chaves; campo que falta vira texto vazio e campo além do cabeçalho é descartado.
No sentido JSON para CSV, a entrada precisa ser um array. Os nomes das colunas saem das chaves do primeiro objeto. Um valor é colocado entre aspas quando contém o separador, uma aspa ou uma quebra de linha, e as aspas internas são duplicadas. Valores nulos viram célula vazia, e as linhas são unidas com quebra de linha simples.
Limitações
- O BOM do UTF-8, marcador invisível que o Excel coloca no início de alguns arquivos, não é removido. Ele fica grudado no nome da primeira coluna, e o código que procura a chave
codigonão a encontra. Salve sem BOM ou apague o primeiro caractere. - Todos os valores saem como texto. Número, preço e booleano não são convertidos.
- No JSON para CSV, colunas que aparecem só a partir do segundo objeto são ignoradas, porque o cabeçalho vem do primeiro. Objeto aninhado vira o texto
[object Object]. - Cabeçalhos repetidos no CSV geram uma única chave, com o valor da última coluna.
- Separadores aceitos: vírgula ou ponto e vírgula. Tabulação não é suportada. Não há upload nem download de arquivo: entrada por colagem, saída pelo botão Copiar.
Privacidade
Os dados não saem do navegador. Planilha de preços antes da publicação, base de clientes ou relatório de vendas podem ser convertidos sem envio ao servidor, e nada é gravado quando a página fecha.
Para continuar
JSON vs XML vs YAML ajuda a decidir o formato de troca entre sistemas, e JSON em Feeds de Produto mostra a estrutura que marketplaces esperam. Depois de converter, confira a sintaxe no Formatador de JSON; se a planilha traz URLs de ofertas, o Gerador de UTM em Massa aplica os parâmetros de campanha à coluna inteira.
Perguntas frequentes
Por que minha planilha virou uma coluna só no JSON?
O arquivo foi exportado com ponto e vírgula, padrão do Excel em português, e a conversão estava usando vírgula. Marque a opção Usar ponto e vírgula como separador. O sintoma costuma vir junto com preços cortados na vírgula decimal.
Por que o nome da primeira coluna não é encontrado no meu código?
Provavelmente o arquivo começa com o BOM do UTF-8, um caractere invisível que fica grudado no primeiro nome de coluna. O texto parece igual, mas a chave é diferente. Exporte como CSV UTF-8 sem BOM ou remova o primeiro caractere antes de converter.
Os preços saem como número no JSON?
Não. Todos os valores do CSV saem como texto, inclusive preços com vírgula decimal como "27,90". A conversão para número, trocando vírgula por ponto, deve ser feita no sistema que vai consumir o JSON.
O que acontece com objetos aninhados na conversão de JSON para CSV?
Eles não são achatados. Um objeto dentro do registro vira o texto [object Object] na célula, e uma lista vira os itens separados por vírgula. Achate a estrutura antes, criando campos como estoque_loja em vez de estoque.loja.
Por que uma coluna sumiu ao converter JSON para CSV?
As colunas do CSV vêm das chaves do primeiro objeto do array. Se uma chave aparece só a partir do segundo item, ela fica de fora. Garanta que o primeiro objeto tenha todas as chaves, mesmo com valor vazio.