Como converter um arquivo JSON para CSV: upload, Excel e linha de comando (Guia 2026)

Por que converter um arquivo JSON é uma habilidade própria

A maioria dos tutoriais de conversão começa com o JSON já na área de transferência. A vida real começa com um arquivo: data.json parado na sua pasta de Downloads, uma exportação de API que você salvou, um backup de algum aplicativo. Trabalhar a partir de um arquivo adiciona uma camada que colar da área de transferência pula — codificações, tamanhos de arquivo, quebras de linha, o formato do que está realmente no disco — e cada uma delas pode mudar silenciosamente o seu resultado.

A boa notícia é que arquivos são mais fáceis num aspecto: eles forçam um fluxo de trabalho repetível. Depois que você conhece o caminho do arquivo .json para o arquivo .csv, ele funciona de forma idêntica seja o arquivo de 3 KB ou 300 MB, seja você fazendo isso uma vez ou cem vezes. Este guia cobre esse fluxo de ponta a ponta: obter o arquivo, verificá-lo, convertê-lo de três formas diferentes e abrir o CSV sem estragá-lo.

De onde vem o seu arquivo JSON (e por que isso importa)

Arquivos JSON chegam de alguns lugares, e saber qual é diz o que esperar por dentro:

Exportações e downloads de APIs. O botão "Exportar" ou "Baixar JSON" de um painel, ou uma chamada curl para uma API que você salvou em disco. Geralmente são matrizes de registros — o formato mais amigável para CSV — mas podem ter centenas de megabytes.
Backups de aplicativos. Aplicativos de mensagens, de notas e gerenciadores de senhas exportam seus dados como JSON. Tendem a ser profundamente aninhados, com objetos dentro de objetos, porque foram feitos para máquinas, não para planilhas.
Ferramentas de desenvolvedor do navegador. Clique com o botão direito numa resposta de rede, "Salvar como", e você tem um arquivo .json. Rápido e prático, mas confira se você salvou o corpo da resposta e não o invólucro HTML em volta dela.
Anexos de e-mail e drives compartilhados. A exportação de um colega que chega como data.json. Trate-os com desconfiança até validar — um anexo que passou por três servidores de e-mail pode pegar danos de codificação.

Antes de tocar em qualquer conversor, abra o arquivo num editor de texto e olhe as primeiras linhas. Se você vir [ no topo, tem uma matriz de registros — ideal. Se vir {, tem um único objeto, possivelmente com estruturas aninhadas que vão precisar de achatamento. Ambos convertem; o segundo só precisa da opção de achatamento ativada.

Passo zero: valide o arquivo antes de converter

Todo conversor desta página vai recusar um arquivo com erro de sintaxe, e a mensagem de erro nem sempre vai dizer onde está o problema. Valide primeiro, converta depois — leva dez segundos e elimina o mistério mais comum de "por que não converte".

A verificação mais rápida não precisa de ferramenta nenhuma se você tem Python instalado. Rode isto contra o seu arquivo; ele não imprime nada em caso de sucesso e sai com um erro apontando a linha culpada em caso de falha:

Terminal

# Validate data.json (quiet on success, points at the error on failure)
python3 -m json.tool data.json > /dev/null && echo "valid JSON"

Os culpados de sempre são vírgulas sobrando, strings entre aspas simples e aspas inteligentes coladas de aplicativos de chat ou documentos — tudo ilegal em JSON. Se você prefere clicar a digitar, nosso guia de formatação de JSON mostra validadores online gratuitos; prefira um que rode no seu navegador para o arquivo ficar na sua máquina.

Uma coisa com que não se preocupar: um arquivo que é uma linha só, enorme. JSON minificado parece alarmante no editor de texto, mas é perfeitamente válido e todos os métodos abaixo lidam com ele — você só não consegue lê-lo, e é exatamente por isso que o validador importa.

Método 1: Envie o arquivo para um conversor online gratuito

Para um arquivo único, enviar vence qualquer outro método em velocidade. Um bom conversor aceita um arquivo .json arrastado tão bem quanto texto colado — você nunca deveria precisar abrir o arquivo e copiar o conteúdo à mão, que é como acontecem danos de codificação e colagens truncadas.

Eis o fluxo, usando nosso conversor gratuito como exemplo:

Abra o conversor e arraste seu arquivo .json para a área de envio (ou clique para procurar). O arquivo é lido direto do disco — sem copiar e colar.
Ajuste as opções antes de converter: ative o achatamento se o arquivo tiver objetos aninhados (o conversor transforma customer.name numa coluna com ponto), escolha o delimitador (vírgula para Excel dos EUA/Reino Unido, ponto e vírgula para a maioria dos países europeus) e mantenha os cabeçalhos ligados.
Clique em converter e baixe o .csv. O arquivo é gerado na aba do seu navegador, então nada é enviado para nenhum servidor.

Como saber se um conversor realmente roda no seu navegador? O teste offline: carregue a página, desconecte a rede e converta. Uma ferramenta client-side continua funcionando. Isso importa porque arquivos JSON de trabalho costumam conter e-mails de clientes, chaves de API ou dados internos — você não quer isso parado no servidor de outra pessoa. Se seu arquivo é sensível, esse teste é inegociável.

O limite prático deste método é o tamanho do arquivo. Abas de navegador lidam confortavelmente com arquivos de alguns megabytes; além disso, a aba fica lenta porque o documento inteiro mora na memória. Se seu arquivo tem dezenas de megabytes ou mais, pule para o método de linha de comando abaixo em vez de brigar com a aba.

Arraste seu arquivo .json para o conversor gratuito

Método 2: Abra o arquivo JSON direto no Excel

Se a planilha é o destino final, você pode pular o intermediário: o Excel moderno abre arquivos JSON nativamente pelo Power Query. É a opção mais limpa quando você vai analisar os dados no Excel de qualquer forma.

No Excel, vá em Dados, depois Obter Dados, depois De Arquivo, depois De JSON, e selecione seu arquivo .json.
O Power Query mostra os registros como tabela. Se alguma coluna tiver registros aninhados, clique no ícone de expandir no cabeçalho da coluna para espalhá-los em colunas próprias — o equivalente visual do achatamento.
Clique em Fechar e Carregar para colocar a tabela numa planilha, depois Arquivo, Salvar Como, CSV para gravar o arquivo .csv.

Duas ressalvas honestas. Primeiro, o Google Sheets não abre arquivos JSON nativamente — não há caminho Arquivo, Importar para .json. Converta para CSV primeiro com um dos outros métodos, depois use Arquivo, Importar. Segundo, cuidado com o delimitador na saída: se o Excel da sua região espera ponto e vírgula, salve ou reexporte com delimitador ponto e vírgula em vez de brigar com o assistente de importação depois.

Método 3: Converta o arquivo pela linha de comando

Quando a conversão é um passo de um trabalho maior — uma exportação diária, um script de build, um pipeline de dados — um script local vence clicar em qualquer ferramenta. Também é o único jeito confortável de lidar com arquivos grandes. Aqui estão os dois comandos que equipes de dados realmente usam, ambos testados nesta máquina contra um arquivo orders.json real.

Python com pandas é o cavalo de batalha: lê o arquivo, achata objetos aninhados em colunas com notação de ponto e grava um CSV com BOM para o Excel detectar UTF-8 automaticamente:

Python

import pandas as pd

# Read the file straight from disk
df = pd.read_json("data.json")

# Flatten nested objects to dot-notation columns (customer.name)
df = pd.json_normalize(df.to_dict("records"))

# utf-8-sig adds a BOM so Excel detects the encoding correctly
df.to_csv("data.csv", index=False, encoding="utf-8-sig")
print(f"wrote data.csv ({len(df)} rows)")

O jq é a opção mais leve quando você só precisa de alguns campos. Esta linha de comando lê orders.json, puxa três campos por registro — incluindo aninhados como customer.name — e imprime CSV RFC 4180 correto na saída padrão. Redirecione para um arquivo e pronto:

Uma alternativa de terminal em uma linha para arquivos

O comando jq abaixo foi testado nesta máquina contra um arquivo JSON real: dois registros de pedido com objetos aninhados de cliente e preço. Ele extraiu o ID do pedido, o nome aninhado do cliente e o total aninhado em linhas CSV entre aspas:

Terminal

$ jq -r '.[] | [.orderId, .customer.name, .pricing.total] | @csv' orders.json
"ORD-1","Ana",10.5
"ORD-2","Bo",7.25

O filtro @csv cuida das aspas e do escape para você, e a sintaxe .customer.name alcança direto os objetos aninhados sem nenhum passo de achatamento. Para trabalho rápido no terminal com arquivos que você já tem abertos, nada vence.

Convertendo muitos arquivos JSON de uma vez

Exportações raramente chegam como um arquivo só. Um despejo mensal pode ser trinta arquivos .json, e convertê-los um por um na aba do navegador é uma tarde lenta. A versão em lote do script Python acima percorre uma pasta, convertendo cada arquivo e nomeando cada CSV pelo arquivo de origem:

Python

import pandas as pd, glob

# Convert every .json file in exports/ to its own .csv
for path in sorted(glob.glob("exports/*.json")):
    df = pd.json_normalize(pd.read_json(path).to_dict("records"))
    out = path.rsplit(".", 1)[0] + ".csv"
    df.to_csv(out, index=False, encoding="utf-8-sig")
    print(f"{path} -> {out} ({len(df)} rows)")

Isto foi testado nesta máquina contra dois arquivos de exemplo: cada um produziu seu próprio CSV com as colunas achatadas orderId,customer.name,pricing.total e uma contagem de linhas impressa por arquivo, para você ver de relance se algum saiu vazio. Um cuidado: o script assume que todos os arquivos têm o mesmo formato. Se sua pasta mistura exportações diferentes, converta cada formato separadamente — unir conjuntos de chaves diferentes num CSV só produz uma grade confusa e esparsa.

Arquivos JSON grandes que travam abas do navegador

Uma aba do navegador guarda o documento inteiro na memória, então arquivos de dezenas ou centenas de megabytes fazem abas congelarem ou caírem. A regra de bolso: alguns megabytes vão bem no navegador; qualquer coisa maior converte localmente. Ferramentas locais não têm o teto de memória da aba:

O jq transmite. Para projeções simples de campos, ele nunca guarda o arquivo inteiro na memória, e é por isso que continua rápido em logs de escala de gigabytes.
Python com pandas lida com centenas de megabytes num laptop comum — o script acima funciona sem mudanças.
Para arquivos verdadeiramente enormes, veja se a exportação pode ser dividida em um objeto JSON por linha (JSON Lines). Arquivos delimitados por linha processam um registro por vez e nunca precisam do documento inteiro na memória de uma vez.

Qualquer que seja o tamanho, valide primeiro: achar um erro de sintaxe num arquivo de 2 GB é muito mais fácil com python3 -m json.tool (ou um validador de streaming) do que vendo um conversor falhar depois de um upload de cinco minutos.

Depois que o CSV chega: abra sem estragar

A conversão pode ser perfeita e a planilha mesmo assim sair errada, porque abrir um CSV já é uma pequena habilidade. Estas são as três correções que resolvem quase todo relato de "meu CSV está quebrado":

Codificação: se caracteres acentuados viram lixo, o arquivo foi lido como ANSI em vez de UTF-8. Importe de novo e defina a origem do arquivo como 65001: UTF-8. (O script Python acima grava um BOM justamente para o Excel detectar isso sozinho.)
Delimitador: se tudo cai numa coluna só, seu Excel espera ponto e vírgula — comum em países europeus. Reexporte com delimitador ponto e vírgula em vez de brigar com a importação.
Zeros à esquerda: CEPs e IDs como 07477 perdem o zero quando a planilha chuta "número". Formate a coluna como texto na importação, ou prefixe com um apóstrofo.

E guarde o arquivo .json original. A conversão lê o arquivo sem alterá-lo — o JSON fica intacto — e arquivá-lo não custa nada. CSV é uma simplificação sem volta: converter de volta não restaura tipos de dados nem desachata suas colunas.

Erros de arquivo e como corrigi-los

Arquivos adicionam modos de falha que texto colado nunca tem. Quando um conversor rejeita seu arquivo, passe por esta lista antes de qualquer outra coisa:

Extensão errada. Um arquivo salvo do Notepad como data.json.txt — ou um .json que na verdade é HTML de um download falhado — não vai analisar. Abra as primeiras linhas: se você vir <html>, baixou uma página de erro, não JSON.
Dano de codificação. Arquivos que passaram por e-mail ou foram salvos com a codificação errada podem carregar mojibake. Salve de novo como UTF-8; na dúvida, o validador do passo zero vai sinalizar o que não consegue ler.
O arquivo está bom, mas é enorme. Veja a seção de arquivos grandes: isso é um problema de ferramenta, não de dados.
Quebras de linha. CRLF versus LF não afeta a análise de JSON de jeito nenhum, então se um conversor culpar as quebras de linha, o problema real está em outro lugar — geralmente um dos itens acima.

Noventa por cento dos relatos de "não converte meu arquivo" terminam num destes quatro. Os outros dez por cento são JSON genuinamente inválido, e o validador aponta direto para a linha culpada.

Qual fluxo de arquivo você deve escolher?

Todo método desta página lê o mesmo arquivo e produz o mesmo CSV para a mesma entrada — a escolha é sobre conveniência, privacidade e escala. Combine com a sua situação:

Um arquivo, alguns megabytes ou menos: arraste para um conversor online gratuito. De longe o mais rápido.
Dados sensíveis no arquivo: um conversor client-side, Excel ou um script local — nada que envie primeiro.
A planilha é o destino: o De JSON do Excel, pulando o conversor.
Muitos arquivos ou uma agenda: o script Python em lote, versionado e reexecutável.
Um arquivo enorme: só ferramentas locais — jq, Python ou processamento delimitado por linha.

E o hábito que sustenta todos eles: valide o arquivo antes de converter, guarde o original depois de converter e confira a codificação ao abrir o CSV. Faça esses três e arquivos JSON viram a entrada mais fácil que você tem.

Guias relacionados

Perguntas frequentes

Posso converter um arquivo JSON para CSV sem instalar nada?

Sim. Arraste o arquivo .json para um conversor online gratuito que roda no seu navegador — sem instalação, sem conta — e baixe o CSV. Se o Excel já estiver instalado, Dados > Obter Dados > De Arquivo > De JSON abre o arquivo nativamente sem nada extra para instalar.

É seguro enviar meu arquivo JSON para um conversor online?

Só se a conversão acontecer no seu navegador. Conversores client-side, como o deste site, leem o arquivo do disco e geram o CSV localmente, então os dados nunca saem da sua máquina. Teste qualquer conversor desconectando a rede depois que a página carregar: se ele ainda converter, é client-side e seguro para arquivos sensíveis.

Por que o Excel joga meu CSV inteiro numa coluna só depois de converter um arquivo JSON?

Seu Excel espera um delimitador diferente — geralmente ponto e vírgula em países europeus. Reexporte o CSV com delimitador ponto e vírgula em vez de brigar com o assistente de importação, ou use Dados > De Texto/CSV e defina o delimitador explicitamente na importação.

Como converto um arquivo JSON muito grande para CSV?

Converta localmente, não numa aba do navegador. O jq transmite arquivos de escala de gigabytes para projeções simples de campos, e um script Python curto com pandas lida com centenas de megabytes num laptop comum. Valide o arquivo primeiro — achar um erro de sintaxe num arquivo enorme é muito mais fácil antes da conversão do que depois de uma tentativa falha.

Posso converter vários arquivos JSON para CSV de uma vez?

Sim — um script curto em lote percorre uma pasta e converte cada arquivo, nomeando cada CSV pelo arquivo de origem. O trecho Python deste guia faz exatamente isso com pandas, imprimindo uma contagem de linhas por arquivo para você detectar resultados vazios. Converta cada formato de dados distinto separadamente para que conjuntos de chaves diferentes não se fundam numa grade confusa.

Meu arquivo JSON não converte. O que está errado?

Quase sempre uma de quatro coisas: o arquivo não é JSON válido (rode python3 -m json.tool para achar o erro), o "JSON" é na verdade uma página de erro HTML de um download falhado, o arquivo é grande demais para uma aba do navegador, ou a extensão mente (data.json.txt). Valide primeiro — ele aponta o problema exato em segundos.

Converter altera ou apaga meu arquivo JSON original?

Não. Todo método deste guia lê o arquivo e grava um CSV novo — o .json original fica intacto. Guarde-o como arquivo: CSV é uma simplificação sem volta, e você não restaura tipos de dados nem estrutura aninhada convertendo o CSV de volta.