Como Converter JSON para CSV (e CSV para JSON) — Guia Prático
Converter JSON para CSV é o passo que separa uma resposta de API de uma planilha que qualquer pessoa consegue abrir. E o caminho inverso, de CSV para JSON, é o que transforma um export de Excel em dados que o seu código entende. Este guia mostra como fazer os dois, o que pode dar errado e por que o separador importa tanto no Brasil.
Índice
- Quando converter JSON para CSV
- O formato que o CSV espera
- Como converter JSON para CSV
- E quando o JSON tem dados aninhados?
- Como converter CSV para JSON
- Convertendo os tipos depois
- Vírgula ou ponto e vírgula?
- Na linha de comando
- Erros comuns
- Perguntas Frequentes
- Ferramentas relacionadas
Quando converter JSON para CSV
- Abrir dados de API no Excel ou Google Sheets para análise, gráficos ou relatório.
- Importar em sistemas (ERP, CRM, plataformas de e-mail) que aceitam CSV, não JSON.
- Compartilhar com pessoas não técnicas, que abrem uma planilha sem pensar duas vezes.
- Fazer uma verificação rápida de milhares de registros, com filtros e ordenação da planilha.
O caminho inverso — CSV para JSON — aparece quando alguém te manda uma planilha e você precisa alimentar um script, um mock de API ou um banco.
O formato que o CSV espera
CSV é uma tabela: uma linha de cabeçalho e uma linha por registro. Para gerar isso a partir de JSON, o ideal é um array de objetos com as mesmas chaves:
[
{ "nome": "Ana", "cidade": "Recife", "ativo": true },
{ "nome": "João", "cidade": "Salvador", "ativo": false }
]
Resultado:
nome,cidade,ativo
Ana,Recife,true
João,Salvador,false
Regras que uma boa conversão aplica sozinha:
- Cabeçalho = a união de todas as chaves encontradas nos objetos.
- Campo que contém vírgula, aspas ou quebra de linha é colocado entre aspas duplas; aspas internas viram
""(padrão RFC 4180). - Valor aninhado (objeto ou array) não cabe numa célula: ele é serializado como texto JSON dentro da coluna.
Como converter JSON para CSV
- Abra o Conversor de JSON para CSV e deixe no modo JSON → CSV.
- Cole o array JSON.
- Escolha o separador (veja a seção abaixo).
- Converta, copie e salve como
.csv— ou cole direto numa planilha.
Antes de converter, vale rodar o JSON pelo Formatador de JSON para enxergar a estrutura e pelo Validador de JSON para garantir que não há vírgula sobrando ou aspas erradas.
Ferramenta gratuita
Converter JSON para CSV agora
Cole o JSON, escolha o separador e copie o CSV pronto para o Excel — ou faça o inverso, de CSV para JSON.
E quando o JSON tem dados aninhados?
Planilha só entende valor simples por célula. Quando um campo é um objeto ou um array, a conversão o transforma em texto JSON dentro da coluna:
[
{ "id": 1, "nome": "Ana", "tags": ["vip", "ativo"], "endereco": { "cidade": "Recife", "uf": "PE" } }
]
vira
id,nome,tags,endereco
1,Ana,"[""vip"",""ativo""]","{""cidade"":""Recife"",""uf"":""PE""}"
Funciona, mas não é o ideal para análise. Se você quer colunas separadas como endereco.cidade e endereco.uf, achate o JSON antes — no seu código:
const achatado = dados.map((d) => ({
id: d.id,
nome: d.nome,
tags: d.tags.join(" | "),
cidade: d.endereco.cidade,
uf: d.endereco.uf,
}));
E então converta achatado, que já é um array de objetos planos.
Como converter CSV para JSON
- No mesmo conversor, mude para CSV → JSON.
- Cole o CSV (a primeira linha precisa ser o cabeçalho).
- Ajuste o separador para o mesmo que o arquivo usa.
- Converta: o resultado é um array de objetos, uma chave por coluna.
Importante: todos os valores saem como texto (string). O CSV não guarda tipo, então "30" continua string até você converter para número no seu código.
Convertendo os tipos depois
Como o CSV não carrega tipo, o array que sai da conversão CSV → JSON tem tudo como string. Para restaurar números, booleanos e datas:
const tipado = registros.map((r) => ({
...r,
idade: Number(r.idade),
ativo: r.ativo === "true" || r.ativo === "1",
criadoEm: new Date(r.criadoEm),
}));
Faça a conversão campo a campo, só nas colunas que você conhece — converter tudo "no automático" costuma quebrar CEPs, telefones e códigos com zero à esquerda (0450 viraria 450).
Vírgula ou ponto e vírgula?
O "C" de CSV é de comma (vírgula), mas o Excel em português costuma usar ponto e vírgula como separador de colunas — porque a vírgula já é o separador decimal (4,50).
- Vai abrir no Excel PT-BR? Gere com ponto e vírgula.
- Vai consumir em código, num sistema internacional ou no Google Sheets? Use vírgula.
- Recebeu um CSV e ele "abre tudo numa coluna só"? O separador do arquivo é diferente do que a planilha espera — reconverta ou use Dados → Texto para Colunas.
Na linha de comando
Para automatizar ou lidar com arquivos grandes, dá para converter sem navegador:
# JSON -> CSV com jq (array de objetos planos)
jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]]) | @csv' dados.json > dados.csv
# CSV -> JSON com Python (biblioteca padrão)
python3 -c 'import csv,json,sys; print(json.dumps(list(csv.DictReader(open("dados.csv"))), ensure_ascii=False, indent=2))'
O jq assume que todos os objetos têm as mesmas chaves; se não tiverem, achate antes. Para transformações mais pesadas, ferramentas como o Miller (mlr) convertem entre JSON, CSV, TSV e mais em um comando.
Erros comuns
- "JSON inválido": quase sempre é vírgula sobrando antes de
]ou}, ou aspas simples no lugar de duplas. O Validador de JSON aponta a linha. - JSON que não é array: um objeto único vira uma linha só. Envolva em
[ ... ]se quiser tratar como lista. - Colunas faltando em algumas linhas: objetos com chaves diferentes geram células vazias — isso é esperado.
- Acentos "quebrados" no Excel: salve o arquivo como UTF-8 (ou use Dados → Obter Dados → De Texto/CSV e escolha a codificação).
Perguntas Frequentes
O JSON precisa ser um array de objetos?
Para um CSV com cabeçalho, sim. Um objeto único é convertido como uma única linha. Estruturas profundamente aninhadas são serializadas como texto JSON dentro da célula.
A conversão preserva números e booleanos?
De JSON para CSV, tudo vira texto. De CSV para JSON, todos os campos saem como string — o CSV não carrega tipo. Converta depois, no código.
Dá para converter um JSON gigante?
Sim, a conversão roda no seu navegador. Arquivos muito grandes (dezenas de MB) podem deixar a aba lenta; nesse caso, use jq ou processe em lotes.
Como abrir o CSV no Excel sem quebrar acentos?
Salve o arquivo em UTF-8 e, no Excel, use Dados → Obter Dados → De Texto/CSV, escolhendo a codificação "65001: Unicode (UTF-8)". Abrir com duplo clique às vezes assume a codificação errada.
Colunas com data e número mudam sozinhas no Excel?
Podem. O Excel interpreta 01/02 como data e remove zeros à esquerda de códigos. Para preservar, importe pelo assistente De Texto/CSV e marque as colunas sensíveis como "Texto".
Meus dados são enviados para algum servidor?
Não. Tudo acontece no navegador (client-side). Nenhum conteúdo é transmitido ou armazenado.
Ferramentas relacionadas
- Conversor de JSON para CSV — os dois sentidos, com escolha de separador
- Formatador de JSON — indente e visualize a estrutura
- Validador de JSON — encontre o erro de sintaxe
- Conversor JSON ↔ YAML — para arquivos de configuração
Para entender quando cada formato faz sentido, leia JSON vs YAML: quando usar cada um e Como formatar JSON.