Como converter JSON para CSV: guia simples

Aprender como converter JSON para CSV é uma daquelas pequenas habilidades que economizam horas de copiar e colar tedioso. APIs, webhooks e aplicativos modernos entregam os dados em JSON, mas planilhas, contadores e ferramentas de relatórios querem linhas e colunas organizadas. Se você já abriu um arquivo JSON no Excel ou no Google Planilhas e viu uma parede de texto espremida em uma única célula, conhece o problema. A boa notícia é que a conversão é simples quando você entende para que serve cada formato, e você pode fazê-la no navegador.

Por que as planilhas querem CSV, e não JSON

JSON e CSV foram criados para trabalhos diferentes. JSON, abreviação de JavaScript Object Notation, foi projetado para que máquinas trocassem dados estruturados. Um único registro pode conter texto, números, listas e outros registros aninhados dentro dele. Essa flexibilidade é o motivo pelo qual os desenvolvedores adoram o formato, e pelo qual as planilhas têm dificuldade com ele: uma planilha é uma grade, e cada valor precisa de uma linha e uma coluna.

CSV, ou valores separados por vírgula, combina perfeitamente com a grade. A primeira linha nomeia as colunas, e cada linha depois dela é um registro. Excel, Google Planilhas, LibreOffice e quase todas as ferramentas de importação de bancos de dados abrem um arquivo CSV diretamente. É por isso que equipes financeiras pedem exportações em CSV, que ferramentas de e-mail aceitam listas de contatos em CSV e que analistas começam a maioria dos projetos transformando respostas de API em CSV.

Arquivos CSV também são texto simples, então são pequenos e fáceis de inspecionar. Uma resposta de API geralmente inclui campos de que você não precisa, como IDs internos e metadados, e converter para CSV obriga você a escolher as colunas importantes. Se o JSON bruto parece uma única linha longa e ilegível, passe-o primeiro por um formatador de JSON para ver sua estrutura.

Como converter JSON para CSV: como é uma conversão limpa

Uma conversão limpa segue uma regra simples: cada objeto JSON vira uma linha, e cada campo vira uma coluna. Os nomes dos campos viram a linha de cabeçalho no topo do arquivo, e os valores se alinham abaixo na mesma ordem. Quando todos os registros têm os mesmos campos, o resultado é uma tabela organizada que qualquer planilha abre sem reclamar.

Três detalhes separam um CSV limpo de um CSV quebrado. Primeiro, o texto que contém uma vírgula deve ficar entre aspas duplas, ou sua planilha vai dividi-lo em duas colunas: um nome de empresa como Smith, Jones and Co precisa de aspas ao redor. Segundo, aspas dentro do texto são duplicadas: she said "hello" vira "she said ""hello""" em CSV. Terceiro, números e datas devem manter um formato consistente, para que os valores usem sempre as mesmas casas decimais.

A codificação também importa. Se seus dados incluem caracteres acentuados ou símbolos de moeda, salve o CSV como UTF-8. O Excel no Windows às vezes lê arquivos UTF-8 incorretamente, então, se nomes acentuados virarem símbolos estranhos, importe o arquivo pelo Assistente de Importação de Texto do Excel e escolha UTF-8 em vez de clicar duas vezes nele. Por fim, verifique se todos os registros têm os mesmos campos; se um deles não tiver um campo, essa célula deve ficar vazia em vez de empurrar os valores seguintes para as colunas erradas.

Dados aninhados: a parte complicada de como converter JSON para CSV

JSON simples é fácil de converter, mas dados reais de API raramente são simples. Um registro de cliente pode conter um objeto de endereço com campos de rua, cidade e CEP, ou uma lista de pedidos anteriores. Uma planilha não tem como guardar um objeto dentro de uma célula, então dados aninhados precisam ser achatados antes de virarem CSV.

A abordagem mais comum é a notação de pontos: cada campo aninhado vira sua própria coluna, com o caminho unido por pontos. Um objeto de endereço com um campo de cidade vira uma coluna chamada address.city, e um CEP vira address.postcode. Isso mantém todas as informações, e os nomes das colunas ainda mostram de onde veio cada valor. Funciona bem quando o aninhamento tem apenas um ou dois níveis de profundidade, o que cobre a maioria das respostas de API.

Listas são mais difíceis, porque um registro pode conter muitos itens. Um pedido com três produtos não cabe em uma única linha sem uma decisão. Você tem três opções: uma linha por item, repetindo os detalhes do pedido, que é o melhor quando você precisa analisar ou somar os itens; juntar os itens em uma única célula, separados por ponto e vírgula, o que mantém uma linha por pedido, mas é mais difícil de analisar; ou dividir os dados em dois arquivos, um para pedidos e outro para itens, ligados por um ID de pedido. Seja qual for sua escolha, aplique-a a todos os registros: misturar abordagens faz com que as colunas signifiquem coisas diferentes em linhas diferentes.

Um exemplo real passo a passo

Suponha que você tenha uma pequena loja online e seu sistema de pedidos entregue este JSON: uma matriz de quatro pedidos, cada um com o nome do cliente, um endereço de e-mail e um valor.

• { "name": "Ana Ruiz", "email": "ana@example.com", "amount": 49.99 }
• { "name": "Ben Carter", "email": "ben@example.com", "amount": 129.50 }
• { "name": "Carla Diaz", "email": "carla@example.com", "amount": 24.00 }
• { "name": "Dan Kim", "email": "dan@example.com", "amount": 89.95 }

É uma estrutura simples e limpa, então a conversão é direta. Os nomes dos campos —name, email e amount— viram a linha de cabeçalho, e cada objeto vira uma linha do arquivo CSV:

• name,email,amount
• Ana Ruiz,ana@example.com,49.99
• Ben Carter,ben@example.com,129.50
• Carla Diaz,carla@example.com,24.00
• Dan Kim,dan@example.com,89.95

Abra esse arquivo em uma planilha e você terá uma tabela organizada com quatro linhas e três colunas, pronta para ordenar, filtrar ou somar. Some os quatro valores —49.99 mais 129.50 mais 24.00 mais 89.95— e o total é 293.44, que deve ser igual ao total do seu sistema de pedidos. Se não for, procure um registro ausente ou duplicado.

Como converter JSON para CSV no navegador

Você não precisa instalar software nem escrever código para converter um arquivo. Um conversor online gratuito faz todo o trabalho: cole seu JSON, confira a prévia e baixe o CSV. O conversor de JSON para CSV funciona totalmente no seu navegador, então seus dados nunca saem do seu computador, o que importa quando o arquivo contém e-mails de clientes ou detalhes de pedidos.

O fluxo habitual leva menos de um minuto. Primeiro, copie o JSON da resposta da sua API ou da sua exportação. Se ele parecer uma única linha comprimida, organize-o primeiro com um formatador de JSON para confirmar que a estrutura é válida. Depois cole-o no conversor, revise os cabeçalhos das colunas na prévia e baixe o CSV. Abra o arquivo baixado no Excel ou no Google Planilhas e verifique três coisas: se os cabeçalhos correspondem aos campos que você esperava, se nenhuma coluna parece deslocada e se o número de linhas corresponde ao número de registros do seu JSON. Se algo parecer errado, o problema quase sempre são dados aninhados ou um campo ausente.

Perguntas frequentes

Posso converter JSON para CSV no Excel sem uma ferramenta online?

Sim. No Excel, use Dados, depois Obter Dados, depois De Arquivo, depois De JSON para carregar o arquivo com o Power Query. O Power Query mostra o JSON como uma tabela que você pode expandir, achatando registros aninhados ao clicar no ícone de expansão de uma coluna. Quando a tabela estiver certa, escolha Fechar e Carregar e depois salve o arquivo como CSV. O Google Planilhas não tem importação de JSON integrada, então, para o Planilhas, um conversor online geralmente é mais rápido.

O que acontece com as matrizes aninhadas do meu JSON?

Matrizes aninhadas precisam ser achatadas antes de virarem CSV, porque uma única célula não consegue conter uma lista de valores de forma útil. A maioria dos conversores cria uma linha por item da matriz, repetindo os campos do registro principal, ou junta os itens em uma única célula com um separador. Escolha uma linha por item quando precisar contar, somar ou filtrar os itens, e uma célula unida apenas quando precisar de uma linha por registro principal.

Por que meu CSV fica quebrado quando abro no Excel?

As causas mais comuns são vírgulas sem aspas dentro do texto, um separador diferente e a codificação. Se um valor contém uma vírgula e não está entre aspas, o Excel o divide em colunas extras. Se seu arquivo usa ponto e vírgula em vez de vírgula, o Excel pode colocar a linha inteira em uma única coluna; importar pelo Assistente de Importação de Texto e escolher o delimitador correto resolve isso. Se caracteres acentuados parecerem errados, importe novamente e escolha a codificação UTF-8.

Agora você sabe como converter JSON para CSV do jeito certo: escolha as colunas importantes, achate os dados aninhados de forma consistente, tome cuidado com vírgulas e aspas, e verifique o número de linhas e um total antes de compartilhar o arquivo. Teste agora com o conversor gratuito de JSON para CSV: cole seu JSON, baixe um CSV limpo e pronto para a planilha, e volte ao trabalho que realmente importa.