Resposta rápidapara converter JSON para CSV, o JSON precisa ser uma lista de registros (um array de objetos): cada objeto vira uma linha e cada chave vira uma coluna. Campos aninhados são achatados em colunas como cliente.nome. Para abrir no Excel em português sem problemas, gere o CSV em UTF-8 com BOM e ponto e vírgula como separador, ou converta direto para XLSX.
O desenvolvedor exporta os pedidos da API, manda o arquivo para o financeiro e recebe de volta: "O que é isso? Eu preciso de uma planilha." JSON é ótimo para sistemas conversarem entre si, mas ninguém fecha o mês lendo chaves e colchetes.
Converter JSON para CSV resolve — desde que você entenda o que acontece com cada parte do arquivo.
Onde o JSON aparece na rotina
Quem trabalha com planilha esbarra em JSON mais do que imagina. Situações típicas:
- Exportação de plataforma de e-commerce: pedidos, clientes e produtos baixados pela API da loja.
- Relatórios de ferramentas de marketing: métricas de campanha exportadas por integração.
- Sistemas internos: o ERP ou o CRM entrega um arquivo .json no botão "exportar dados".
- Formulários e pesquisas: respostas coletadas por ferramentas online.
- Pedidos de portabilidade de dados: muitos serviços entregam os dados do usuário em JSON.
O volume também engana. Uma exportação de 20 mil pedidos facilmente passa de 10 MB em JSON, porque cada registro repete o nome de todas as chaves. Em CSV, o nome das colunas aparece uma vez só, no cabeçalho, e o arquivo tende a ficar bem menor.
JSON e CSV: duas formas de guardar os mesmos dados
O CSV é uma tabela em texto puro: uma linha de cabeçalho e uma linha por registro, com os valores separados por vírgula (ou ponto e vírgula). A especificação de referência é a RFC 4180.
O JSON é uma estrutura hierárquica: objetos dentro de objetos, listas dentro de listas. A especificação é a RFC 8259.
A conversão funciona bem quando o JSON tem "formato de tabela": uma lista de registros com campos parecidos.
“json [ { "id": 101, "cliente": "Ana", "total": 159.9 }, { "id": 102, "cliente": "Bruno", "total": 89.5 } ] “
Vira:
| id | cliente | total |
|---|---|---|
| 101 | Ana | 159.9 |
| 102 | Bruno | 89.5 |
O formato que muitas APIs devolvem
Muitas APIs não entregam a lista solta, e sim dentro de um envelope, com metadados de paginação:
“json { "data": [ { "id": 101 }, { "id": 102 } ], "page": 1 } “
Nesse caso, a tabela está na chave data. Boas ferramentas reconhecem esse envelope; outras exigem que você extraia a lista antes.
O que fazer com campos aninhados
Aqui está o ponto em que a maioria das conversões rápidas falha. Veja um pedido real de loja virtual:
“json { "id": 101, "cliente": { "nome": "Ana", "cidade": "Recife" }, "itens": ["camiseta", "boné"] } “
Objetos viram colunas com ponto
O objeto cliente não cabe numa célula. A solução padrão é achatar: cada campo interno vira uma coluna com o caminho completo no nome.
| id | cliente.nome | cliente.cidade |
|---|---|---|
| 101 | Ana | Recife |
Sem achatar, a célula mostraria algo como [object Object], que não serve para nada.
Listas são o caso difícil
A lista itens não tem representação tabular única. Há três caminhos, cada um com custo:
- Gravar a lista como texto JSON na célula:
["camiseta","boné"]. Preserva tudo e permite voltar ao original, mas a célula não é fácil de filtrar. - Juntar com vírgula:
camiseta, boné. Fica legível, mas quebra se algum item tiver vírgula no nome. - Uma linha por item: o pedido 101 aparece duas vezes, uma por produto. É o melhor para análise, mas exige uma transformação a mais e duplica os outros campos.
Para relatórios rápidos, o primeiro caminho costuma bastar. Para análise de itens vendidos, vale pedir ao desenvolvedor uma exportação já com uma linha por item.
Registros com campos diferentes
APIs costumam omitir campos vazios. O primeiro registro pode não ter cupom, e o quinto ter. Uma conversão bem-feita usa a união das chaves de todos os registros como cabeçalho, não só as do primeiro. Do contrário, colunas inteiras desaparecem sem aviso.
Pasta Mágica
Converta a exportação da API em planilha
Solte o JSON e baixe um CSV com objetos achatados em colunas, cabeçalho completo e acentos que o Excel entende.
Como abrir o CSV no Excel sem dor de cabeça
Um CSV tecnicamente correto ainda pode abrir mal no Excel em português. Os dois problemas clássicos têm solução simples.
Acentos quebrados
Se "João" aparece como "João", o Excel leu o arquivo com a codificação errada. Gravar o CSV em UTF-8 com BOM — três bytes invisíveis no início do arquivo — faz o Excel reconhecer a codificação. O guia de CSV com acentos errados explica o problema em detalhe.
Tudo numa coluna só
No Brasil, a vírgula é o separador decimal. Por isso, o Excel com configuração regional brasileira costuma esperar ponto e vírgula como separador de colunas. Um CSV com vírgulas abre com todos os campos espremidos na coluna A. Veja mais em CSV com ponto e vírgula.
| Destino do arquivo | Separador recomendado | Observação |
|---|---|---|
| Excel em português | Ponto e vírgula | Ou converter direto para XLSX |
| Sistemas e bancos de dados | Vírgula | Padrão da RFC 4180 |
| Dados com muitas vírgulas no texto | Tabulação | Evita confusão com o conteúdo |
A saída mais à prova de erro, quando o destino é uma pessoa e não um sistema, é pular o CSV e entregar um XLSX: o Excel abre sem perguntar nada sobre separador ou codificação. Se você já tem o CSV, veja como converter CSV para Excel.
Passo a passo para converter JSON para CSV
- Confira a estrutura: abra o JSON e veja se é um array de objetos ou um envelope com a lista em
data. - Decida o tratamento dos aninhados: achatar objetos em colunas e, para listas, aceitar o texto JSON na célula ou pedir outra exportação.
- Escolha o separador conforme o destino: ponto e vírgula para Excel em português, vírgula para sistemas.
- Grave em UTF-8 com BOM, se o arquivo for aberto no Excel.
- Converta e confira: número de linhas igual ao número de registros, cabeçalho com todas as colunas.
- Se for para uma pessoa, gere também o XLSX.
E se o arquivo for enorme?
Segundo as especificações publicadas pela Microsoft (consulte a central de suporte do Excel), uma planilha comporta no máximo 1.048.576 linhas. Exportações maiores precisam ser divididas antes de abrir. O guia de como dividir um CSV grande mostra como fazer isso mantendo o cabeçalho em cada parte.
Antes e depois
Antes: o desenvolvedor escreve um script descartável a cada pedido do financeiro, ou alguém cola o JSON num site qualquer e reza para os acentos sobreviverem.
Depois: a exportação vai para um fluxo fixo que converte, aplica o separador certo e entrega a planilha. O desenvolvedor volta para o código; o financeiro recebe o arquivo no formato de sempre.
Perguntas frequentes
Não diretamente. CSV é uma tabela: linhas e colunas. O JSON precisa ser uma lista de registros parecidos (um array de objetos) para virar linhas. Um objeto único, ou uma estrutura muito profunda, precisa ser reorganizado antes.
A forma mais comum é achatar: o campo cliente.nome vira uma coluna chamada cliente.nome. Assim cada valor ganha a sua própria coluna, em vez de aparecer como texto ilegível na célula.
Não existe forma única de colocar uma lista numa célula. Algumas ferramentas gravam a lista como texto JSON na célula; outras criam uma linha por item. Se você precisa analisar os itens, a segunda abordagem exige um passo de transformação a mais.
O Excel nem sempre reconhece arquivos UTF-8 sozinho. Um CSV gravado com BOM, uma marca invisível no início do arquivo, faz o Excel identificar a codificação e mostrar João em vez de João.
O Excel configurado para o Brasil costuma esperar ponto e vírgula como separador, porque a vírgula é usada nos decimais. Gere o CSV com ponto e vírgula ou converta direto para XLSX.
Como automatizar isso com a Pasta Mágica
Na Pasta Mágica, a conversão de JSON para CSV é uma etapa que pode terminar em planilha do Excel. Tudo roda com bibliotecas tradicionais de dados, sem IA interpretando o arquivo.
- Crie sua conta em pastamagica.com.br/cadastrar e teste com uma exportação real.
- No app, escolha JSON para CSV ou monte um fluxo com ela seguida de CSV para Excel, para entregar um XLSX.
- Ajuste as opções: separador (vírgula, ponto e vírgula, tabulação ou barra vertical), BOM para o Excel, achatamento de objetos em colunas
pai.filhoe tipo de quebra de linha. - Solte os arquivos JSON (até 100 MB e 500 mil registros por arquivo). A etapa aceita um array na raiz ou um objeto com a lista na chave
data, e monta o cabeçalho com as chaves de todos os registros. Listas internas vão como texto JSON na célula. - Acompanhe e baixe os CSVs ou planilhas prontos, um a um ou em ZIP.
O custo em créditos aparece antes de rodar, e se uma etapa falhar a reserva volta sozinha. Os limites de cada plano estão na tabela de preços.
Pasta Mágica
Da exportação da API à planilha do financeiro
Converta JSON em CSV e CSV em Excel em sequência. Você solta o arquivo; a pasta faz o resto.
