JSON para CSV e Vice-Versa: Guia Completo para Desenvolvedores

· 12 min de leitura

Converter entre os formatos JSON e CSV é uma daquelas tarefas cotidianas que todo desenvolvedor encontra. Seja exportando dados de API para análise, importando dados de planilhas para sua aplicação ou transformando dados entre sistemas, entender essas conversões por completo vai te poupar inúmeras horas de frustração.

Este guia cobre tudo, desde conversões básicas até o tratamento de estruturas aninhadas complexas, streaming de arquivos grandes e casos extremos que confundem até desenvolvedores experientes.

Índice

Quando Usar JSON vs CSV

Antes de mergulhar nas técnicas de conversão, vamos entender quando cada formato brilha. Fazer a escolha certa desde o início pode te poupar de conversões desnecessárias e dores de cabeça com estruturas de dados.

Pontos Fortes do JSON

JSON (JavaScript Object Notation) se destaca quando você precisa de flexibilidade e estrutura. É o formato preferido para aplicações web modernas e APIs por boas razões.

Pontos Fortes do CSV

CSV (Comma-Separated Values) é o cavalo de batalha dos dados tabulares. Existe desde os anos 1970 e não vai a lugar nenhum.

Cenários Comuns de Conversão

Aqui está quando você normalmente precisará converter entre formatos:

Cenário Direção Por quê
Análise de dados de API JSON → CSV Buscar dados de uma API, analisar no Excel ou ferramentas de ciência de dados
Exportações de banco de dados CSV → JSON Exportar do banco de dados, enviar através de API REST
Revisão de configuração JSON → CSV Converter arquivos de configuração complexos para planilha para revisão de stakeholders
Importação de dados em massa CSV → JSON Importar dados de planilha para aplicação web
Migração de dados Ambas direções Mover dados entre sistemas com diferentes requisitos de formato

Dica profissional: Se você precisa converter dados frequentemente, considere usar nosso Conversor de JSON para CSV ou Conversor de CSV para JSON para conversões rápidas baseadas no navegador sem escrever código.

Python: Conversão de JSON para CSV

Python oferece múltiplas abordagens para conversão JSON-CSV. Vamos explorar tanto a biblioteca pandas (melhor para a maioria dos casos de uso) quanto o módulo csv da biblioteca padrão (quando você quer zero dependências).

Usando Pandas (Recomendado)

Pandas é o canivete suíço da manipulação de dados em Python. Para conversão de JSON para CSV, é difícil de superar.

import pandas as pd
import json

# Método 1: De arquivo
with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

df = pd.DataFrame(data)
df.to_csv('output.csv', index=False, encoding='utf-8')

# Método 2: De string JSON
json_string = '{"users": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}'
df = pd.read_json(json_string)
df.to_csv('users.csv', index=False)

# Método 3: De URL (endpoint de API)
df = pd.read_json('https://api.example.com/data')
df.to_csv('api_data.csv', index=False)

Tratando JSON Aninhado com json_normalize

Quando seu JSON tem objetos aninhados, json_normalize achata a estrutura em um formato tabular.

from pandas import json_normalize
import json

# Exemplo de JSON aninhado
nested_data = {
    "users": [
        {
            "name": "Alice",
            "age": 30,
            "address": {
                "city": "New York",
                "country": "USA"
            }
        },
        {
            "name": "Bob",
            "age": 25,
            "address": {
                "city": "London",
                "country": "UK"
            }
        }
    ]
}

# Achatar estrutura aninhada
df = json_normalize(nested_data['users'])
# Colunas serão: name, age, address.city, address.country

df.to_csv('flattened_users.csv', index=False)

Usando Biblioteca Padrão (Sem Dependências)

Se você não pode instalar pandas ou quer uma solução leve, o módulo csv integrado do Python funciona muito bem para conversões simples.

import csv
import json

# Ler arquivo JSON
with open('data.json', 'r', encoding='utf-8') as json_file:
    data = json.load(json_file)

# Assumindo que data é uma lista de dicionários
if isinstance(data, list) and len(data) > 0:
    # Obter cabeçalhos do primeiro item
    headers = data[0].keys()
    
    # Escrever para CSV
    with open('output.csv', 'w', newline='', encoding='utf-8') as csv_file:
        writer = csv.DictWriter(csv_file, fieldnames=headers)
        writer.writeheader()
        writer.writerows(data)

Dica rápida: Sempre use index=False ao chamar to_csv() no pandas. Caso contrário, você terá uma coluna extra com números de linha que provavelmente não quer.

JavaScript/Node.js: Conversão de JSON para CSV

Desenvolvedores JavaScript têm excelentes opções para conversão JSON-CSV, tanto no Node.js quanto no navegador.

Usando Biblioteca json2csv (Node.js)

A biblioteca json2csv é a escolha mais popular para aplicações Node.js. Ela lida com cenários complexos com facilidade.

const { Parser } = require('json2csv');
const fs = require('fs');

// Conversão simples
const data = [
  { name: 'Alice', age: 30, city: 'New York' },
  { name: 'Bob', age: 25, city: 'London' },
  { name: 'Charlie', age: 35, city: 'Tokyo' }
];

const parser = new Parser();
const csv = parser.parse(data);

fs.writeFileSync('output.csv', csv);

// Com opções personalizadas
const customParser = new Parser({
  fields: ['name', 'age', 'city'], // Especificar ordem das colunas
  delimiter: ';', // Usar ponto e vírgula em vez de vírgula
  quote: '"',
  header: true
});

const customCsv = customParser.parse(data);
fs.writeFileSync('custom_output.csv', customCsv);

JavaScript Puro (Compatível com Navegador)

Para conversões baseadas no navegador ou quando você quer zero dependências, aqui está uma implementação limpa:

function jsonToCsv(jsonData) {
  if (!jsonData || jsonData.length === 0) {
    return '';
  }
  
  // Obter cabeçalhos do primeiro objeto
  const headers = Object.keys(jsonData[0]);
  
  // Criar linha de cabeçalho CSV
  const csvHeaders = headers.join(',');
  
  // Criar linhas de dados CSV
  const csvRows = jsonData.map(row => {
    return headers.map(header => {
      const value = row[header];
      
      // Tratar valores que contêm vírgulas ou aspas
      if (typeof value === 'string' && (value.includes(',') || value.includes('"'))) {
        return `"${value.replace(/"/g, '""')}"`;
      }
      
      return value;
    }).join(',');
  });
  
  // Combinar cabeçalho e linhas
  return [csvHeaders, ...csvRows].join('\n');
}

// Uso
const data = [
  { name: 'Alice', age: 30, city: 'New York' },
  { name: 'Bob', age: 25, city: 'London' }
];

const csv = jsonToCsv(data);
console.log(csv);

Baixando CSV no Navegador

Aqui está como acionar um download de CSV do navegador:

function downloadCsv(jsonData, filename = 'data.csv') {
  const csv = jsonToCsv(jsonData);
  
  // Criar blob
  const blob = new Blob([csv], { type: 'text/csv;charset=utf-8;' });
  
  // Criar link de download
  const link = document.createElement('a');
  const url = URL.createObjectURL(blob);
  
  link.setAttribute('href', url);
  link.setAttribute('download', filename);
  link.style.visibility = 'hidden';
  
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
}

// Uso
const users = [
  { name: 'Alice', email: '[email protected]' },
  { name: 'Bob', email: '[email protected]' }
];

downloadCsv(users, 'users.csv');

Conversão de CSV para JSON

Converter CSV para JSON é igualmente importante, especialmente ao importar dados de planilhas ou sistemas legados.

Python: CSV para JSON

import pandas as pd
import json

# Método 1: Usando pandas (mais simples)
df = pd.read_csv('input.csv')
json_data = df.to_json(orient='records', indent=2)

# Salvar em arquivo
with open('output.json', 'w', encoding='utf-8') as f:
    f.write(json_data)

# Método 2: Usando biblioteca padrão
import csv
import json

with open('input.csv', 'r', encoding='utf-8') as csv_file:
    csv_reader = csv.DictReader(csv_file)
    data = list(csv_reade