← Todos os artigos
Atualizado em May 29, 20267 min read

Como converter JSON para CSV (e voltar)

Converta JSON para CSV e CSV para JSON — em JavaScript, Python e online. Cobre o mapeamento array-de-objetos, regras de aspas, valores aninhados e coerção de tipos.

JSON é a língua das APIs; CSV é a língua das planilhas, dos bancos de dados e dos analistas. Converter entre os dois é tarefa diária —— exportar uma resposta de API para Excel ou transformar uma planilha em JSON para importação. Este guia mostra como converter JSON em CSV e CSV em JSON, em JavaScript, em Python e instantaneamente no navegador —— além dos casos limite (dados aninhados, aspas, tipos) em que mais se tropeça.

O mapeamento central: Array de objetos ⇄ Linhas

Um arquivo CSV é uma tabela: uma linha de cabeçalho com nomes de colunas, depois uma linha por registro. A forma JSON que mapeia naturalmente para essa tabela é um array de objetos, onde cada objeto é uma linha e cada chave é uma coluna.

// JSON
[
  { "id": 1, "name": "Ada Lovelace", "active": true },
  { "id": 2, "name": "Bob Khan", "active": false }
]
# CSV
id,name,active
1,Ada Lovelace,true
2,Bob Khan,false

O cabeçalho é a união das chaves de todos os objetos (assim, objetos com campos diferentes continuam alinhados), e cada linha pega o valor correspondente para cada coluna.

Como converter JSON em CSV no JavaScript

Não existe um JSON.toCSV embutido, mas a conversão é curta. O único trabalho de verdade é o escape: qualquer valor que contenha uma vírgula, aspas duplas ou quebra de linha precisa ficar entre aspas duplas, e aspas internas são duplicadas.

function jsonToCsv(rows) {
  if (!rows.length) return '';
  const headers = [...new Set(rows.flatMap(Object.keys))];

  const escape = (v) => {
    if (v == null) return '';
    const s = typeof v === 'object' ? JSON.stringify(v) : String(v);
    return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
  };

  const lines = [headers.join(',')];
  for (const row of rows) {
    lines.push(headers.map((h) => escape(row[h])).join(','));
  }
  return lines.join('\n');
}

Note o ramo typeof v === 'object': um objeto ou array aninhado não tem representação CSV plana, então a convenção comum é serializá-lo como texto JSON dentro da célula. Mais sobre isso abaixo.

Como converter CSV em JSON no JavaScript

O problema no sentido inverso é fazer parsing de CSV corretamente —— campos podem conter vírgulas e quebras de linha dentro de aspas, então não basta split(','). Use uma pequena máquina de estados (ou, em produção, uma biblioteca como papaparse):

function csvToJson(text) {
  const rows = [];
  let row = [], field = '', inQuotes = false;
  for (let i = 0; i < text.length; i++) {
    const c = text[i];
    if (inQuotes) {
      if (c === '"' && text[i + 1] === '"') { field += '"'; i++; }
      else if (c === '"') inQuotes = false;
      else field += c;
    } else if (c === '"') inQuotes = true;
    else if (c === ',') { row.push(field); field = ''; }
    else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
    else if (c !== '\r') field += c;
  }
  if (field || row.length) { row.push(field); rows.push(row); }

  const [headers, ...data] = rows;
  return data.map((cells) =>
    Object.fromEntries(headers.map((h, i) => [h, cells[i] ?? ''])));
}

Como converter JSON e CSV em Python

A biblioteca padrão do Python já traz —— sem dependências.

import csv, json, io

# JSON -> CSV
rows = json.loads(json_text)
buf = io.StringIO()
writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
writer.writeheader()
writer.writerows(rows)
csv_text = buf.getvalue()

# CSV -> JSON
rows = list(csv.DictReader(io.StringIO(csv_text)))
json_text = json.dumps(rows, indent=2)

Os casos limite que realmente importam

Objetos e arrays aninhados

CSV é plano; JSON não. Quando o valor é um objeto ou array, você tem duas opções: serializá-lo como JSON dentro de uma célula (simples, reversível) ou achatá-lo em várias colunas como address.city, address.zip (legível, mas com perda e difícil de reverter). Para ida e volta, JSON-em-célula é mais seguro.

CSV perde tipos

CSV não tem tipos —— cada campo é texto. Ao passar de CSV para JSON, "1" é string a menos que você converta deliberadamente para número. Cuidado com valores como 007 (um CEP/ID que precisa continuar sendo string) ou inteiros enormes que perdem precisão ao virar Number. Converta apenas quando a ida e volta for sem perda.

Aspas e delimitadores

Sempre coloque entre aspas campos com vírgulas, aspas ou quebras de linha. Algumas localidades (comum no Excel europeu) usam ; como delimitador —— se o seu CSV aparecer torto em alguma coluna, verifique primeiro o delimitador.

Chaves inconsistentes

Se seus objetos JSON não compartilham todas as chaves, construa o cabeçalho com a união das chaves e deixe as células faltantes em branco —— não assuma que o primeiro objeto define todas as colunas.

Excel e o BOM UTF-8

Se seu CSV vai ser aberto no Excel e contém caracteres não ASCII, prefixe com um BOM UTF-8 (os bytes 0xEF 0xBB 0xBF). O Excel lê UTF-8 sem BOM como uma codificação legada e estraga acentos/caracteres asiáticos. A maioria das bibliotecas CSV emite o BOM via uma opção.

// JavaScript —— escrever um BOM para o Excel ler UTF-8 corretamente
const out = '\uFEFF' + jsonToCsv(rows);

Delimitadores alternativos (CSV vs TSV vs ;)

„CSV“ nem sempre é separado por vírgulas. Variantes comuns:

  • TSV —— separado por tabulações; mais seguro quando valores costumam conter vírgulas.
  • Excel europeu emite ; como delimitador em regiões onde a vírgula é o separador decimal.

Se a saída parece amontoada em uma única coluna estranha ao abrir, o arquivo usa um delimitador diferente do esperado pelo leitor. Padronize um (CSV com , + BOM para Excel multirregional, ou TSV para pipelines de engenharia).

Para CSV do mundo real, use o PapaParse

Para fazer parsing em navegador/Node de CSV vindo de usuários, use PapaParse —— cuida da detecção de delimitador, campos entre aspas, valores multilinha, linhas de cabeçalho e dynamicTyping para converter números e booleanos. Os trechos feitos à mão acima funcionam para entradas simples e confiáveis; em escala, usa-se o PapaParse.

Converter JSON em CSV online —— sem instalação

Para uma conversão pontual, pule o código por completo. Cole seu JSON no conversor JSON para CSV do fixjson e clique em To CSV, ou cole CSV e clique em To JSON. Ele cuida do escape, da união de chaves e da coerção de tipos automaticamente, e roda totalmente no navegador —— nada é enviado, importante quando os dados contêm registros de clientes ou exportações internas.

Perguntas frequentes

Como converto JSON em CSV?

Pegue um array JSON de objetos, construa uma linha de cabeçalho com a união de todas as chaves e escreva uma linha por objeto —— colocando entre aspas qualquer valor com vírgula, aspas ou quebra de linha. Use csv.DictWriter em Python, uma pequena função em JavaScript, ou cole no conversor online.

Como converto CSV em JSON?

Faça o parsing do CSV (respeitando campos entre aspas), trate a primeira linha como cabeçalho e mapeie cada linha subsequente para um objeto com esses cabeçalhos como chaves. Lembre que todos os valores chegam como string, a menos que você converta.

Como objetos JSON aninhados são representados em CSV?

CSV não aninha, então um objeto ou array aninhado normalmente é escrito como texto JSON dentro de uma única célula, ou achatado em colunas com pontos como address.city. JSON-em-célula é a opção reversível.

Posso converter JSON em CSV online de graça?

Sim —— o conversor do fixjson faz as duas direções de graça, totalmente no navegador, sem conta nem upload.

Ferramentas e guias relacionados