Como criar um CSV a partir de JSON: 7 decisões que transformam dados brutos em um arquivo que funciona (guia 2026)

Criar não é o mesmo que converter

As pessoas dizem \"criar um CSV\" e \"converter JSON para CSV\" como se fossem a mesma coisa. Não são. Converter é mecânico: o mesmo JSON sempre produz o mesmo CSV com as mesmas configurações. Criar é autoria: o arquivo que você entrega a um colega, importa para um banco de dados ou alimenta uma ferramenta de análise precisa sobreviver a ambientes que você não controla — o Excel em outro país, um carregador de banco de dados com regras rígidas, um colega que abre tudo com dois cliques.

A distância entre \"convertido\" e \"criado\" é de sete decisões. Pule-as e o arquivo ainda converte; ele só quebra em algum ponto adiante, no pior momento possível. A boa notícia: cada decisão leva segundos, e depois que você entende o que ela é, nunca mais vai deixar de enxergá-la. Todos os exemplos abaixo passaram pelo mecanismo de conversão real deste site — o mesmo JavaScript que roda quando você aperta Converter — então as saídas mostradas são exatamente o que você vai obter.

Decisão 1: achate a árvore antes de desenhar a grade

Você não consegue criar colunas a partir de um JSON aninhado. Um CSV é uma grade — linhas e colunas, cada célula com um único valor simples — e objetos aninhados não têm coluna onde morar. Então a primeira decisão é achatar: objetos aninhados viram colunas com notação de ponto (customer vira customer.name e customer.city), listas de valores simples se juntam em uma célula só e valores nulos viram células vazias. Essa é a etapa mecânica, e é a que o conversor faz por você com a opção de achatamento.

Por que fazer isso primeiro? Porque todas as decisões seguintes — nomes de cabeçalho, delimitadores, aspas — operam sobre o resultado achatado. Se você renomear os cabeçalhos antes de achatar, está nomeando colunas que ainda não existem. O mecanismo aqui achata por padrão com a opção chamada flattenNested, então na prática essa decisão é: deixe ativado, olhe a pré-visualização e confirme se os nomes das colunas são os que você esperava.

Decisão 2: nomeie as colunas como um contrato

Os nomes da linha de cabeçalho são um contrato com todas as ferramentas que um dia vão tocar o arquivo. Nomes de cabeçalho ruins são a forma mais silenciosa de criar um CSV ruim: eles nunca falham na hora da conversão, falham na importação para o banco de dados três semanas depois. Quatro regras cobrem quase tudo:

Sem espaços nos nomes de cabeçalho. \"order id\" é legível para você e um relatório de bug para um carregador SQL; use orderId ou order_id. O mecanismo de achatamento já produz nomes pontuados sem espaços (customer.name), então só as suas chaves de nível superior precisam de atenção.
Sem nomes duplicados. Dois cabeçalhos idênticos fazem a segunda coluna sobrescrever silenciosamente a primeira em muitos importadores. Se o seu JSON tem tanto a chave literal \"user.name\" quanto um objeto aninhado user: { name }, o achatamento funde os dois em uma coluna só — o valor aninhado vence e o outro se perde. Renomeie antes de converter se os dois valores importam.
Sem dígitos no início. Nomes de coluna como \"2024-sales\" quebram em muitos dialetos SQL e em algumas ferramentas de BI. Prefira sales_2024.
Estáveis e por extenso. Um cabeçalho é uma API: abreviar \"qty\" é aceitável, mas \"q\" vai confundir alguém daqui a seis meses. Escolha palavras completas uma vez e reuse-as em todos os arquivos.

Uma coisa para não temer: cabeçalhos com caracteres não-ASCII. Se as suas colunas são product_name e rótulos em japonês como \"商品名\", o UTF-8 carrega tudo sem problema (a Decisão 6 trata da codificação). O mecanismo escreve as células de cabeçalho com as mesmas regras de aspas das células de dados, então até um cabeçalho com vírgula ou aspas sai escapado corretamente — verificamos a lógica de escape no código-fonte; as aspas são aplicadas por célula, cabeçalhos incluídos.

Decisão 3: escolha o delimitador de propósito

A vírgula é o delimitador padrão, e para a maioria dos arquivos ela é a escolha certa. Mas o delimitador não é uma formalidade — é o caractere pelo qual o arquivo inteiro é interpretado. O conversor oferece vírgula, ponto e vírgula, tabulação, pipe e personalizado, e aqui vai quando cada um merece o seu lugar:

Vírgula: o padrão. Use-a a menos que tenha um motivo para não usar. Toda ferramenta a entende.
Ponto e vírgula: quando os seus dados estão cheios de vírgulas. Exportações europeias usam muito isso — não por acaso, porque muitos países europeus usam a vírgula como separador decimal, então um arquivo delimitado por vírgula seria ambíguo. Se os seus campos de texto estão cheios de vírgulas, o ponto e vírgula mantém as células legíveis sem depender das aspas.
Tabulação: quando pessoas vão ler o arquivo bruto. Valores separados por tabulação colam direto em planilhas e continuam legíveis em um editor de texto. Útil para fluxos de copiar e colar.
Pipe: quando o seu texto contém vírgulas, aspas E ponto e vírgula — mensagens de log, endereços, textos corridos. O pipe é raro dentro de texto natural, então quase nunca colide.

A ressalva honesta: as aspas existem justamente para tornar a escolha do delimitador sobrevivível. Quando uma célula contém o delimitador, o mecanismo a envolve em aspas automaticamente (Decisão 4), então um endereço cheio de vírgulas em um arquivo delimitado por vírgula continua sendo interpretado corretamente. A escolha do delimitador é sobre legibilidade e os hábitos do seu público, não sobre correção — a correção é trabalho do mecanismo de aspas. Um aviso real, porém: se você escolher ponto e vírgula para um público nos EUA ou no Reino Unido, avise — o Excel deles pode esperar vírgulas por padrão e abrir o seu arquivo como uma única coluna gigante.

Decisão 4: deixe as aspas no automático

As aspas são a parte mais incompreendida do CSV. A regra é simples: uma célula que contém o delimitador, uma aspa ou uma quebra de linha precisa ser envolvida em aspas duplas, e qualquer aspa dentro dela precisa ser duplicada. Veja o que o mecanismo realmente produz — verificado, não ilustrado:

Aspas em ação (verificado contra o mecanismo real)

name,city,qty
"Say ""hi"", friend",Oslo,3

Leia com atenção: a célula Say \"hi\", friend virou \"Say \"\"hi\"\", friend\" — envolvida em aspas porque contém uma vírgula, e com as aspas internas duplicadas. Essa é a saída correta, conforme o padrão, e todo programa de planilha de verdade a interpreta de volta para exatamente o texto original.

Decisão 4: deixe as aspas no automático (continuação)

Troque o delimitador para ponto e vírgula e veja as aspas se adaptarem:

Mesmos dados, delimitador ponto e vírgula (verificado)

name;city;qty
"Say ""hi"", friend";Oslo;3

A vírgula já não dispara o envolvimento em aspas, mas a aspa continua disparando — o mecanismo coloca aspas de acordo com o delimitador em uso, não com uma ideia fixa do que é \"especial\". Essa consciência por delimitador é o que \"automatic\" significa, e é a configuração que você deve deixar quieta. O mecanismo também oferece os modos de aspas always e never; never é uma armadilha, e aqui está a prova:

Decisão 4: deixe as aspas no automático (continuação)

quoteMode \"never\" — a armadilha (verificado)

note,code
line1
line2,007

Com as aspas desativadas, uma célula com uma quebra de linha de verdade continua crua — e essa quebra de linha agora parece um limite de linha para todo interpretador do planeta. O seu arquivo de 2 linhas é lido como 3 linhas, uma delas lixo. As aspas continuam sendo duplicadas (o mecanismo faz isso incondicionalmente), mas nada é envolvido. Use \"never\" apenas quando um sistema de destino exigir explicitamente saída sem aspas e você tiver verificado que nenhuma célula contém delimitadores, aspas ou quebras de linha. Em todos os outros casos: automático.

Decisão 5: faça os valores parecerem o texto que você quer ver

O JSON tem tipos — números, booleanos, nulos. O CSV tem exatamente um tipo: texto. O momento da conversão é quando cada valor vira a sua forma final de texto, e essa é a decisão que a maioria das pessoas nunca toma conscientemente. Três formatos de valor merecem a sua atenção:

Primeiro, zeros à esquerda. Uma string JSON como \"007\" continua 007 no CSV — verificamos, sem aspas, exatamente como digitada. Mas abrir esse arquivo no Excel ainda vai mostrar 7, porque o Excel reinterpreta as células ao abrir. O CSV está correto; o visualizador é que tem opinião. Se os zeros à esquerda precisam sobreviver ao Excel, a correção é no lado de quem recebe (importar como texto), não no arquivo — saiba disso antes de culpar o conversor.

Segundo, datas. O JSON não tem tipo de data, então as suas \"datas\" são strings como 2026-10-14 ou timestamps como 1697000000. O formato que você converter é o formato que o CSV guarda, então escolha o formato legível para humanos antes de exportar: o ISO 2026-10-14 ordena corretamente como texto; 10/14/2026 não ordena, e vai ser lido errado por metade do mundo. Tome a decisão no JSON, não depois que o CSV já existir.

Terceiro, decimais e booleanos. Um número como 19.99000001 vira exatamente esse texto; booleanos viram true/false. Se os seus dados de origem têm ruído de ponto flutuante, arredonde antes de converter — o CSV não vai arredondar por você.

Decisão 6: escolha o UTF-8 de forma consciente — e entenda a questão do BOM

Codificação é a decisão que ninguém toma até o mojibake obrigar. UTF-8 é a resposta em 2026: ele carrega todos os idiomas, e toda ferramenta moderna o lê. A sutileza é o BOM — a marca de ordem de bytes invisível que algumas ferramentas do Windows querem no início do arquivo.

Aqui vai o fato honesto sobre o conversor deste site: o download sai em UTF-8 puro, sem BOM — lemos o código de download, que cria um Blob text/csv com charset=utf-8 e sem marca inicial. Isso é correto para uploads web, bancos de dados, Google Sheets e Python. O único lugar onde isso morde: dar dois cliques no arquivo em algumas versões do Excel para Windows, que podem adivinhar a codificação errada e embaralhar caracteres não-ASCII.

A correção não é exigir um BOM do conversor — é uma importação de 20 segundos: no Excel, Dados → De Texto/CSV → escolha 65001 (UTF-8) na lista de codificação. Os seus caracteres saem perfeitos e o arquivo continua limpo para todas as outras ferramentas. Decida a sua codificação uma vez por fluxo de trabalho e documente-a junto do arquivo; surpresas de codificação são sempre falha de comunicação, nunca falha de dados.

Decisão 7: valide o arquivo final antes que ele saia das suas mãos

Criar termina com uma conferência, e ela leva menos de um minuto. Quatro passos:

Abra primeiro em um editor de texto, não em uma planilha. Um editor de texto mostra o arquivo; uma planilha mostra a interpretação dele. Verifique a linha de cabeçalho, o delimitador e se as células com aspas parecem sãs.
Conte as linhas. O mecanismo informa a contagem de linhas e colunas nas estatísticas — compare com o tamanho do seu array JSON. Uma divergência significa uma surpresa de interpretação (geralmente uma quebra de linha sem aspas no quoteMode \"never\", ou um JSON de entrada malformado).
Reimporte. Cole o CSV de volta ou abra-o na ferramenta para a qual você vai enviá-lo. Se abrir corretamente lá, vai abrir corretamente para o destinatário.
Confira as bordas: a primeira linha, a última linha e uma linha com os caracteres mais estranhos. Corrupção se concentra nas fronteiras.

Esta lista também é a resposta para \"por que meu CSV parece quebrado\": na nossa experiência, nove vezes em dez o problema é o visualizador ou as configurações de importação, e o arquivo em si na décima. O hábito de abrir primeiro no editor de texto é o que separa os dois em segundos.

A receita de 60 segundos, com as sete decisões

Cole ou envie o seu JSON para o conversor. Deixe o achatamento ativado e olhe a pré-visualização das colunas — aqueles nomes pontuados são os seus cabeçalhos, então renomeie na origem qualquer chave problemática antes. Mantenha a vírgula como delimitador, a menos que o seu texto seja cheio de vírgulas (aí ponto e vírgula). Deixe as aspas no automático. Faça datas e números parecerem o texto que você quer ver antes de converter. Baixe o arquivo em UTF-8, abra uma vez em um editor de texto, reimporte onde ele vai ser usado. Pronto — um arquivo criado, não apenas convertido.

Abrir o conversor gratuito de JSON para CSV

Guias relacionados

Perguntas frequentes

Como faço para criar um arquivo CSV a partir de JSON?

Cole ou envie o seu JSON para um conversor, achate os dados aninhados em colunas, revise os nomes de cabeçalho e o delimitador e baixe. A lista completa: achate primeiro, nomeie as colunas sem espaços, mantenha a vírgula a menos que os dados sejam cheios de vírgulas, deixe as aspas no automático, formate datas e números como o texto que você quer ver, baixe em UTF-8 e reimporte o arquivo uma vez para validar.

Qual é o melhor delimitador para um CSV criado a partir de JSON?

A vírgula é o padrão e a escolha certa para a maioria dos arquivos. Use ponto e vírgula quando os campos de texto estiverem cheios de vírgulas (comum em exportações europeias, onde a vírgula também é o separador decimal), tabulação para legibilidade no copiar e colar, e pipe quando o texto contiver vírgulas, aspas e ponto e vírgula. Aspas corretas fazem qualquer um deles ser interpretado com segurança — a escolha é sobre os hábitos do seu público, não sobre correção.

Como devo nomear as colunas de um CSV criado a partir de JSON?

Trate os nomes de cabeçalho como um contrato: sem espaços (order_id, não \"order id\"), sem duplicatas, sem dígitos no início (sales_2024, não 2024-sales) e palavras completas em vez de abreviações crípticas. Chaves aninhadas achatadas já saem como nomes pontuados sem espaços, como customer.name — geralmente só as suas chaves de nível superior precisam de atenção.

Por que meu CSV abre errado no Excel depois de criá-lo a partir de JSON?

Nove vezes em dez o arquivo está certo e o problema é o visualizador. Causas comuns: o Excel adivinhando o delimitador errado (um arquivo com ponto e vírgula aberto como vírgula), adivinhação errada de codificação em texto não-ASCII (reimporte via Dados → De Texto/CSV com 65001 UTF-8) ou o Excel reinterpretando células (removendo zeros à esquerda como 007 ou reformatando datas). Abra o arquivo primeiro em um editor de texto — se estiver certo lá, o arquivo está certo.

Preciso de aspas em volta de cada célula do CSV?

Não — aspas automáticas (quando necessário) são corretas e suficientes: células com o delimitador, aspas ou quebras de linha são envolvidas em aspas duplas, com as aspas internas duplicadas. \"always\" adiciona ruído, e \"never\" é perigoso: uma quebra de linha sem aspas dentro de uma célula parece um limite de linha para todo interpretador e corrompe silenciosamente a sua contagem de linhas.

Meu CSV criado a partir de JSON deve ter BOM?

Geralmente não. Um arquivo UTF-8 sem BOM funciona em todo lugar: bancos de dados, uploads web, Google Sheets, Python. Algumas versões do Excel para Windows leem errado arquivos sem BOM ao dar dois cliques — a correção é uma importação adequada (Dados → De Texto/CSV, codificação 65001) em vez de adicionar um BOM, que pode confundir outras ferramentas. O conversor deste site baixa UTF-8 puro sem BOM.

Como verifico se o meu CSV gerado está correto?

Quatro passos rápidos: abra em um editor de texto (não em uma planilha) para ver o arquivo de verdade, compare a contagem de linhas com o tamanho do seu array JSON, reimporte na ferramenta para a qual você vai enviá-lo e inspecione a primeira linha, a última linha e a linha com os caracteres mais estranhos. Corrupção se concentra nas fronteiras — se as bordas estão certas, o arquivo está certo.

Crie seu CSV agora — achatamento, aspas e cabeçalhos resolvidos

Cole o JSON ou envie um arquivo: os dados aninhados viram colunas limpas, delimitadores e aspas ficam no automático, e o download sai em UTF-8 puro. Grátis, sem cadastro, roda inteiramente no seu navegador.

Abrir o conversor de JSON para CSV

Todos os guias