FlowingDev

JSON para Excel: Domando Dados de API para Meros Mortais

Aprenda o basicão de como converter dados JSON estruturados, geralmente de APIs, em uma planilha Excel simples e legível, pronta pra análise e relatórios.

Testar a ferramenta: JSON para Excel

Em uma frase

É um tradutor digital que pega uma lista de objetos de dados complexos e aninhados (JSON) e os achata, transformando-os em uma grade bidimensional simples (uma planilha do Excel) que qualquer um consegue ler.

O problema que ele resolve

De um lado do mundo digital, temos desenvolvedores, APIs e bancos de dados. Eles falam em JSON (JavaScript Object Notation), uma linguagem lindamente estruturada, leve e perfeita para máquinas trocarem informações. É a língua franca dos serviços web modernos.

Do outro lado, temos analistas de negócios, gerentes de marketing, product owners e, basicamente, uma fatia enorme do mundo profissional. Eles falam a língua das planilhas. Excel, Google Sheets — essas ferramentas são a interface universal para analisar dados. Você pode ordenar, filtrar, criar gráficos e fazer cálculos sem precisar de código.

O problema é que esses dois mundos não falam a mesma língua. Um desenvolvedor puxa uma lista de 10.000 novos usuários de uma API e recebe uma gloriosa, porém apavorante, muralha de texto cheia de chaves e colchetes. Se ele enviar esse arquivo JSON por e-mail para um gerente de marketing que pediu os dados, é tão útil quanto entregar a ele o esquema de um motor de dobra espacial. Está tecnicamente correto, mas completamente ilegível para o público-alvo.

Historicamente, unir esses dois mundos era uma tarefa manual e chata para um desenvolvedor. Para cada pedido como "Pode me passar uma lista de todos os produtos vendidos no último trimestre?", um dev precisaria:

  1. Buscar os dados.
  2. Escrever um script customizado (em Python, Node.js ou alguma outra linguagem).
  3. Descobrir como lidar com todos os pedaços de dados aninhados.
  4. Exportar para um arquivo CSV ou Excel.
  5. Enviar o arquivo por e-mail.

Este processo é lento, repetitivo e tira os desenvolvedores da tarefa de criar features de verdade. Um conversor de JSON para Excel automatiza toda essa tradução, transformando uma tarefa de desenvolvimento recorrente em uma operação simples, sob demanda e self-service.

Como funciona por debaixo dos panos

Transformar uma estrutura JSON cheia de voltas em uma planilha mais plana que uma panqueca não é mágica, mas envolve alguns passos inteligentes. Vamos descascar as camadas.

Passo 1: Fazer o "parsing" do JSON

Primeiro de tudo, a ferramenta não pode trabalhar com JSON como uma string de texto cru. Ela precisa converter esse texto em uma estrutura de dados que possa de fato manipular, como um array de objetos nativo do JavaScript. Esse passo é chamado de parsing.

Durante o parsing, a ferramenta também atua como um leão de chácara, verificando se a entrada é válida. Ela garante que o JSON esteja bem-formado (sem vírgulas faltando ou colchetes descasados) e, para este trabalho específico, que a estrutura de nível superior seja um array de objetos. Um único objeto como { "name": "Bob" } não pode virar uma tabela, mas um array como [{ "name": "Bob" }] pode virar uma tabela com uma linha.

// Isto é o que a ferramenta recebe: uma string.
'[{"id": 1, "user": {"name": "Alice"}}, {"id": 2, "user": {"name": "Bob"}}]'

// Após o parsing, torna-se uma estrutura que o código pode usar.
// (Esta é uma representação em JavaScript)
[
  { id: 1, user: { name: "Alice" } },
  { id: 2, user: { name: "Bob" } }
]

Passo 2: A Arte do "Flattening" (Achatamento)

Este é o coração de toda a operação. Uma planilha é uma grade bidimensional: linhas e colunas. Um objeto JSON pode ser multidimensional, com objetos aninhados dentro de outros objetos. O "flattening" é o processo de pegar essa estrutura aninhada e representá-la em uma única dimensão.

A técnica mais comum é percorrer o objeto e construir novas chaves juntando as chaves pai e filho com um separador, como um ponto (.) ou um underscore (_).

Vamos pegar um único objeto do nosso array:

{
  "orderId": "ORD-123",
  "customer": {
    "id": 87,
    "contact": {
      "name": "Charlie",
      "email": "charlie@example.com"
    }
  },
  "items": ["Laptop", "Mouse"],
  "shipped": true
}

Quando achatado, ele se torna um objeto simples, de um nível só. Note como as chaves aninhadas customer.id e customer.contact.email são formadas:

{
  "orderId": "ORD-123",
  "customer.id": 87,
  "customer.contact.name": "Charlie",
  "customer.contact.email": "charlie@example.com",
  "items": "Laptop, Mouse",  // Arrays precisam de um tratamento especial!
  "shipped": true
}

O array de items foi simplesmente unido em uma string separada por vírgulas. Esta é uma estratégia comum para arrays simples de valores (strings ou números), pois mantém a saída legível.

Passo 3: Descobrindo os Cabeçalhos (Headers) e Montando a Grade

Uma planilha precisa de uma linha de cabeçalho. Mas e se um objeto no seu JSON tiver um campo que outro não tem? Isso é comum com esquemas de API flexíveis.

[
  { "id": 1, "name": "Alice", "status": "active" },
  { "id": 2, "name": "Bob", "lastLogin": "2023-10-26" }
]

Uma ferramenta ingênua poderia apenas olhar para o primeiro objeto e decidir que os cabeçalhos são id, name e status. Ela então ignoraria completamente o campo lastLogin do Bob.

Um conversor robusto itera através de todos os objetos do array primeiro, coletando todas as chaves achatadas únicas que encontra. Para o exemplo acima, ele descobriria o conjunto completo de cabeçalhos: id, name, status e lastLogin.

Com os cabeçalhos definidos, a ferramenta pode agora montar a grade. Ela cria uma linha para cada objeto JSON e itera através da lista de cabeçalhos. Para cada cabeçalho, ela procura o valor correspondente no objeto achatado daquela linha. Se o valor existir, ele o coloca na célula. Se não existir (como o lastLogin para Alice ou status para Bob), ela deixa a célula em branco.

id name status lastLogin
1 Alice active
2 Bob 2023-10-26

Passo 4: Montando o Arquivo .xlsx

Você tem sua grade de cabeçalhos e dados. E agora? Você não pode simplesmente salvá-la como um arquivo de texto e chamá-lo de .xlsx. O formato .xlsx (conhecido como Office Open XML) é surpreendentemente complexo. Na verdade, é um arquivo ZIP contendo uma coleção de arquivos e pastas XML que descrevem o conteúdo, a estrutura e o estilo da pasta de trabalho.

Uma boa ferramenta de JSON para Excel usa uma biblioteca especializada (como a SheetJS no mundo JavaScript) para cuidar deste passo final. A biblioteca pega a grade de dados e gera programaticamente todos os arquivos XML necessários (xl/worksheets/sheet1.xml, [Content_Types].xml, etc.), que definem as células, linhas e strings compartilhadas. Em seguida, ela empacota tudo em um único arquivo ZIP e dá a ele a extensão .xlsx. Quando você clica duas vezes nesse arquivo, o Excel sabe exatamente como descompactar e interpretar seu conteúdo para renderizar a planilha que você espera.

Histórias da vida real

A Analista de Marketing na Correria

Sarah, uma analista de marketing, recebeu a tarefa de descobrir quais features do novo produto SaaS da empresa eram mais populares. A equipe de engenharia forneceu a ela um endpoint de API que retornava um array JSON gigante de atividade dos usuários. Era denso, aninhado e totalmente incompreensível para ela. Ela pediu ajuda a um desenvolvedor, mas ele estava atolado de trabalho. Frustrada, ela encontrou uma ferramenta web de JSON para Excel. Ela colou o JSON, clicou em um botão e baixou uma planilha limpa e organizada. Em uma hora, ela havia criado tabelas dinâmicas e gráficos que mostravam que o "dashboard de relatórios" era um sucesso com os clientes corporativos, mas a "feature de colaboração" mal estava sendo usada.

Lição: Essas ferramentas dão autonomia para membros não técnicos da equipe, permitindo que eles mesmos obtenham os dados de que precisam, economizando tempo de desenvolvimento e acelerando os insights de negócio.

O Desenvolvedor que Prototipa APIs

Alex estava construindo uma nova API para uma plataforma de e-commerce. O product manager (PM) queria "ver os dados" antes que Alex passasse semanas na implementação. Em vez de construir um backend temporário, Alex simplesmente "mockou" alguns objetos JSON representativos do que a API iria produzir — incluindo informações aninhadas de clientes, itens de pedido e detalhes de envio. Ele passou esse JSON de exemplo por um conversor e enviou o arquivo Excel resultante para o PM. O PM notou imediatamente que o item_price estava faltando e que o customer_address deveria ser dividido em vários campos. Eles pegaram a falha de design em minutos.

Lição: Um conversor é uma fantástica ferramenta de comunicação e prototipagem, ajudando a alinhar a implementação técnica com os requisitos de negócio antes que uma única linha de código de produção seja escrita.

A Dor de Cabeça da Migração de Dados

Uma pequena empresa estava desativando um CRM antigo, construído sob medida, e migrando para uma solução de prateleira. A única opção de exportação do sistema antigo era um arquivo JSON massivo contendo todos os registros de clientes. O novo sistema só podia importar dados via Excel ou CSV. O JSON era profundamente aninhado. O desenvolvedor encarregado da tarefa temia ter que escrever um script de migração pontual — um trabalho de vários dias para uma ferramenta que seria usada exatamente uma vez. Em vez disso, ele dividiu o JSON gigante em pedaços gerenciáveis e passou cada um por um conversor. Ele então combinou os arquivos Excel resultantes, fez uma pequena limpeza e importou tudo com sucesso para o novo CRM em menos de meio dia.

Lição: Para tarefas pontuais de transformação de dados, um conversor dedicado pode ser vastamente mais eficiente do que escrever e depurar scripts customizados.

Erros e armadilhas comuns

  • Ignorar os tipos de dados. Uma conversão preguiçosa pode transformar tudo em string no Excel. Números viram texto ("123" em vez de 123), fazendo com que somas e cálculos falhem. O valor null do JSON pode se tornar a string "null" em vez de uma célula vazia. Uma boa ferramenta respeita os tipos, mapeando números JSON para números do Excel, booleanos para VERDADEIRO/FALSO e null para células em branco.
  • Lidar mal com arrays de objetos. Vimos como um array de strings simples (["Laptop", "Mouse"]) pode ser unido. Mas e um array de objetos, como vários endereços para um usuário? Uma ferramenta ruim pode simplesmente cuspir "[object Object],[object Object]" na célula, o que é lixo. Ferramentas melhores podem criar linhas duplicadas (uma para cada endereço) ou expandi-los em colunas numeradas (endereco_0_rua, endereco_1_rua), mas você precisa estar ciente de como a ferramenta escolhida se comporta.
  • Esquecer de objetos inconsistentes. Se o seu conversor inspecionar apenas o primeiro objeto no array para determinar as colunas, você vai perder dados. Sempre garanta que a ferramenta examine o conjunto de dados inteiro para construir uma lista completa de cabeçalhos antes de gerar a planilha.
  • Alimentá-lo com uma baleia. Ferramentas que rodam no navegador têm limites de memória. Se você tentar colar um arquivo de log JSON de 500 MB em uma ferramenta web, seu navegador provavelmente vai travar e fechar com tudo. Para conjuntos de dados realmente massivos, uma ferramenta de linha de comando ou um script dedicado ainda é a abordagem correta.
  • Assumir a ordem das colunas. A ordem das chaves em um objeto JSON não é garantida pela especificação. Embora a maioria dos parsers mantenha a ordem original hoje em dia, você não deve criar um fluxo de trabalho que dependa de as colunas aparecerem em uma sequência específica.

Por que isso deve estar no seu radar

Você deve pensar em usar um conversor de JSON para Excel sempre que houver a necessidade de mover dados do mundo das máquinas para o mundo dos humanos. É uma peça fundamental no seu kit de ferramentas para:

  • Compartilhar rapidamente respostas de API com colegas não técnicos.
  • Prototipar e visualizar estruturas de dados para novos projetos.
  • Realizar análises de dados simples sem precisar subir um banco de dados ou uma plataforma de BI.
  • Lidar com tarefas pontuais de importação/exportação de dados entre sistemas que não falam a mesma língua.

Sempre que você ouvir a frase, "Você pode só me arrumar uma lista de...", e a fonte for um endpoint JSON, um conversor deveria ser seu primeiro pensamento. É o atalho definitivo para a democracia dos dados.

Vá mais fundo

Teoria feita. Hora de pôr a mão na massa — 100% no seu navegador.

Testar a ferramenta: JSON para Excel