Conversor de JSON para CSV

O que esta página faz e por que ela existe

Esta ferramenta recebe um arquivo JSON — por upload ou arrastando o arquivo para a área indicada — e o converte em um arquivo CSV. Você escolhe o delimitador do CSV de saída (vírgula, ponto e vírgula ou tabulação), visualiza uma prévia da tabela convertida e faz o download do resultado. Todo o processamento ocorre dentro do seu navegador: nenhum dado é enviado para nenhum servidor.

A diferença central entre esta conversão e outras (como CSV para Excel ou Excel para JSON) é a direção da transformação. Aqui você está achatando um formato de dados hierárquico e tipado (JSON) em uma tabela plana e sem tipos (CSV). JSON suporta objetos, arrays, números, booleanos e null em estruturas aninhadas. CSV não tem tipos, não tem aninhamento, não tem múltiplas abas e não preserva formatação. A conversão, portanto, descarta toda a informação de tipo, toda a estrutura aninhada e qualquer formatação que exista no JSON original.

Para representar objetos JSON aninhados dentro das células de uma linha de CSV, a ferramenta usa a notação de caminho por pontos (dot‑path). Por exemplo, um campo "endereco": { "cidade": "São Paulo", "uf": "SP" } vira duas colunas: endereco.cidade e endereco.uf. Arrays de objetos viram linhas da tabela; arrays de arrays são mantidos como linhas, com cada elemento interno ocupando uma coluna.

Como o achatamento de JSON funciona na prática

A primeira regra que a ferramenta impõe é que o JSON de entrada precisa ser tabular — ou seja, uma única array de objetos ou uma array de arrays. Se você enviar um JSON que seja um objeto único ou uma estrutura profundamente aninhada sem uma array externa, o conversor exibirá o erro “This JSON is invalid or not table‑shaped.” (em português, “Este JSON é inválido ou não tem formato de tabela”).

Vamos a um exemplo concreto. Suponha este JSON válido e tabular:

[
  {
    "nome": "Maria",
    "telefones": ["11-99999-0001", "11-99999-0002"],
    "endereco": { "rua": "Rua A", "numero": 100 }
  },
  {
    "nome": "João",
    "telefones": ["21-88888-0003"],
    "endereco": { "rua": "Rua B", "numero": 200 }
  }
]

Para convertê-lo, a ferramenta percorre a array de objetos. O primeiro objeto define as chaves que se tornarão cabeçalhos das colunas. Como telefones é uma array, ela permanece como uma única coluna cujo valor será a representação textual da array (por exemplo, ["11-99999-0001","11-99999-0002"]). Já endereco é um objeto aninhado, então ele é expandido: as chaves internas rua e numero são combinadas com o prefixo endereco., gerando as colunas endereco.rua e endereco.numero. O CSV resultante terá as seguintes colunas: nome, telefones, endereco.rua, endereco.numero. Cada linha corresponde a um objeto da array.

Se o JSON for uma array de arrays como [["a", 1], ["b", 2]], o conversor trata cada array interna como uma linha, e os elementos individuais como colunas. Não há busca por chaves — os cabeçalhos são gerados automaticamente como Column 1, Column 2, etc.

Delimitador e regras de citação em CSV

Você pode escolher entre três delimitadores no momento da conversão: vírgula (,, o padrão ISO para CSV), ponto e vírgula (;) ou tabulação (\t). A escolha importa porque muitos softwares de planilha (Excel, Google Sheets, LibreOffice Calc) usam o ponto e vírgula como separador quando o sistema operacional está configurado para um locale que usa vírgula como separador decimal. Usar o delimitador errado pode fazer com que o arquivo seja aberto completamente desalinhado.

Independentemente do delimitador escolhido, a ferramenta aplica automaticamente as regras de citação definidas na RFC 4180 para CSV. Isso significa que valores que contenham o próprio delimitador, quebras de linha ou aspas duplas são envolvidos por aspas duplas. As aspas duplas internas ao valor são escapadas duplicando‑as. Exemplo: se um campo contém "Olá, mundo" e o delimitador é vírgula, o valor no CSV será """Olá, mundo""". Se houver uma quebra de linha no valor do campo, ele será envolvido por aspas e a quebra de linha ficará dentro das aspas.

Esse tratamento automático é uma faca de dois gumes: ele garante que o CSV seja bem formado, mas também significa que, ao reimportar o CSV gerado, os tipos originais (números, booleanos) já foram perdidos — tudo virou string.

A perda de tipos e outras limitações estruturais

O CSV não tem tipos de dados. Números, booleanos e null são convertidos para strings. Isso tem consequências que muitas vezes pegam usuários desprevenidos:

• Números com zeros à esquerda (ex.: "00123") perdem os zeros se o valor original for numérico em JSON (123), porque o JSON não preserva zeros à esquerda em números. O CSV conterá 123, não 00123. Se o zero à esquerda for importante (códigos postais, IDs), o JSON precisa representar o valor como string ("00123"), não como número.
• Booleanos (true, false) viram as strings "true" e "false", sem distinção no CSV.
• Valores nulos (null) viram strings vazias ou a string literal "null", dependendo da implementação — nesta ferramenta, o campo fica vazio.
• Objetos aninhados são achatados com caminho de pontos, mas arrays internas não são expandidas em várias linhas. Uma array dentro de um objeto vira uma única coluna com a representação textual da array. Se você precisa que cada elemento da array vire uma linha separada, isso exige um processo de normalização que a ferramenta não faz — você precisa fazer essa transformação antes de fornecer o JSON.

Além disso, o JSON deve ser table‑shaped. O que isso significa exatamente? A ferramenta espera que o topo da estrutura seja uma array. Se cada objeto dentro dessa array tiver um conjunto diferente de chaves, o CSV terá colunas para todas as chaves encontradas no primeiro objeto, e as demais linhas podem ter células vazias. Não há mesclagem inteligente de cabeçalhos — a ferramenta usa as chaves do primeiro objeto como cabeçalho definitivo.

Limites, erros e mensagens que você pode encontrar

A ferramenta impõe limites para evitar travamentos no navegador. Embora o valor exato dependa da versão, o comportamento documentado inclui:

• Tamanho do arquivo: se o arquivo exceder um limite máximo (não especificado na interface, mas mencionado na documentação), o erro é “This file is too large. Use a file under ‹max›.” (em português, “Este arquivo é grande demais. Use um arquivo abaixo de ‹max›.”).
• Número de linhas: se a tabela tiver mais do que o máximo permitido de linhas, o erro é “This table has more than ‹max› rows.”
• Número de colunas: o mesmo para colunas — “This table has more than ‹max› columns.”
• Outros erros comuns:
  • “Choose one file first.” — você não selecionou nenhum arquivo.
  • “Choose a CSV, JSON or XLSX file.” — o arquivo selecionado tem extensão diferente das aceitas.
  • “Choose a different output format.” — você selecionou o mesmo formato para entrada e saída sem necessidade de conversão.
  • “Could not convert this file.” — erro genérico de processamento, muitas vezes causado por JSON malformado.
  • “Conversion cancelled.” — o usuário interrompeu manualmente.
  • “This conversion is taking too long. Try a smaller file.” — o navegador atingiu o tempo limite de execução.

Todas essas mensagens aparecem na interface. Como a conversão é local, não há logs de servidor para consultar; você precisa corrigir o arquivo de entrada e tentar novamente.

Quem realmente precisa desta ferramenta e por quê

Três perfis de usuário se beneficiam diretamente:

1. Quem recebe dados de APIs REST. Muitas APIs devolvem JSON com listas de objetos. Para analisar esses dados em uma planilha ou em um banco de dados relacional, você precisa de CSV. A conversão local é essencial se os dados são sensíveis (dados pessoais, financeiros, sigilosos) — você não quer enviá-los para um servidor terceiro.
2. Quem trabalha em pipelines de dados rápidos. Em prototipação, você pode ter um arquivo JSON de teste e querer convertê-lo para CSV para carregar em uma ferramenta de BI. A conversão instantânea no navegador acelera o ciclo.
3. Quem precisa de um delimitador específico. Se você está em um locale que usa vírgula como decimal (Brasil, Portugal, França, etc.), a abertura automática de CSV com vírgula no Excel pode gerar dados bagunçados. Poder escolher ponto e vírgula no momento da conversão resolve esse problema sem precisar reconfigurar o software.

O ponto central, repetindo o que torna esta página única, é a direção da conversão: de hierárquico para plano, com perda de tipos. Quem já está acostumado a converter de Excel para JSON talvez estranhe a ausência de opções de estrutura. Aqui o achatamento é automático e rígido.

Perguntas frequentes

1. O que acontece se meu JSON tiver um objeto aninhado com vários níveis?

A ferramenta achata recursivamente usando a notação de ponto. Um campo a.b.c se torna uma coluna com a concatenação de todas as chaves internas. Não há limite de profundidade, mas quanto mais níveis, mais colunas e mais difícil a leitura em CSV.

2. Posso converter um JSON que contenha arrays dentro de objetos múltiplas vezes?

Sim, mas o conteúdo da array será representado como string textual no CSV. Por exemplo, `` vira "". A ferramenta não expande arrays em múltiplas linhas — isso exigiria uma transformação de unnest que não está disponível.

3. A ferramenta preserva a codificação de caracteres (acentos, emojis)?

Sim, porque o processamento é feito no navegador usando a codificação UTF-8 padrão do arquivo JSON. O CSV gerado também é UTF-8. Ao abrir em alguns editores de texto ou versões antigas do Excel, pode ser necessário importar explicitamente como UTF-8 para evitar caracteres quebrados.

4. Perdi meus zeros à esquerda. Como evitar?

Certifique-se de que no JSON original o valor esteja entre aspas (string). Um número 00123 em JSON não é válido — o parser lê como 123. Use "00123". A ferramenta preservará a string como está.

5. Meu arquivo JSON é inválido ou não é tabular. O que faço?

Use um validador JSON como JSONLint para verificar a sintaxe. Depois, confira se o conteúdo é uma array de objetos ou uma array de arrays. Se for um único objeto, coloque‑o dentro de colchetes: [{... }].

6. A ferramenta aceita JSON com mais de um array no mesmo arquivo?

Não. A ferramenta espera um único array no nível raiz. Se o arquivo tiver múltiplos arrays (por exemplo, {"dados": [...], "metadados": [...]}), a estrutura não é tabular e o erro será exibido.