Como converter dados JSON aninhados em arquivo CSV

Para converter JSON aninhado em CSV, use um conversor de JSON para CSV online que permita escolher qual array JSON será transformado nas linhas do CSV. Essa escolha é mais importante do que muita gente imagina. Exportações JSON reais geralmente começam com metadados, paginação ou objetos de encapsulamento, enquanto os registros desejados ficam em um caminho como results, data.items ou payload.records.

Normalmente, trato a conversão de JSON para CSV como três decisões:

• Qual array deve ser transformado em linhas?
• Quais campos de objetos aninhados devem virar colunas?
• Quais arrays devem ser unidos, mantidos como JSON ou expandidos em linhas próprias?

Depois de responder a essas perguntas, o restante segue um fluxo de trabalho de CSV convencional. Você visualiza o resultado, confere as colunas e baixa um arquivo CSV compatível com planilhas, CRM, ferramentas de BI ou processos de limpeza de dados.

📌 A versão resumida

Comece decidindo o que cada linha do CSV deve representar. Neste exemplo, quero uma empresa por linha; portanto, o nó de linhas será $.results. Depois, posso nivelar as métricas da empresa e decidir o que fazer com arrays como contacts e tags.

Neste guia, usarei uma exportação JSON aninhada com 20.000 registros de empresas dentro de results. O mesmo processo funciona com respostas de API, resultados de scraping, logs de webhook, exportações de CRM e dados de marketplaces nos quais os registros relevantes não estão na raiz do JSON.

Links rápidos:

• Exemplo de arquivo JSON aninhado
• Converter JSON aninhado em CSV no Datablist
• Escolher o nó de linhas correto
• Nivelar objetos JSON aninhados
• Tratar arrays dentro das linhas JSON
• Revisar e baixar o CSV

Exemplo de arquivo JSON aninhado

Para este exemplo, imagine uma grande exportação JSON proveniente de uma API ou ferramenta de scraping. O arquivo tem cerca de 8,8 MB e contém 20.000 registros em um array results no nível superior.

O objeto raiz tem esta estrutura:

{
  "meta": {
    "generatedAt": "2026-07-04T10:00:00Z",
    "source": "stress_test"
  },
  "results": [
    {
      "id": 0,
      "name": "NbDXeG4Gyg",
      "website": "https://example-0.com",
      "contacts": [
        {
          "name": "Ava Martin",
          "emails": ["ava@example-0.com"],
          "phones": ["+1 555 0100"]
        },
        {
          "name": "Noah Lee",
          "emails": ["noah@example-0.com"],
          "phones": []
        }
      ],
      "tags": "enterprise",
      "metrics": {
        "employees": 124,
        "revenue": {
          "amount": 476171,
          "currency": "USD"
        }
      },
      "createdAt": "2026-06-25T09:12:00Z"
    },
    {
      "id": 1,
      "name": "DwwGmkzmBi",
      "website": "https://example-1.com",
      "contacts": [
        {
          "name": "Mia Chen",
          "emails": ["mia@example-1.com"],
          "phones": ["+1 555 0101"]
        }
      ],
      "tags": ["saas", "mid-market"],
      "metrics": {
        "employees": 47,
        "revenue": null
      },
      "createdAt": "2026-06-26T14:33:00Z"
    }
  ]
}

Esse é o tipo de arquivo que costuma causar problemas em conversores básicos. Os registros não estão no objeto raiz, mas dentro de results. Além disso, contêm objetos e arrays aninhados, valores que alternam entre strings e arrays, valores nulos e datas.

🔍 Por que este arquivo é um bom teste

Um array JSON simples e plano só testa o cenário mais fácil. Este arquivo coloca à prova as decisões importantes em exportações reais: metadados de encapsulamento, um array de registros aninhado, campos de objeto, campos de array, valores mistos e valores nulos.

Veja a estrutura das primeiras linhas:

O CSV de destino deve ter uma linha por empresa. Quero campos úteis como id, name, website, employees, amount, currency e createdAt em colunas. Para campos como contacts e tags, preciso decidir quanto da estrutura original preservar.

Converter JSON aninhado em CSV no Datablist

Abra o conversor de JSON do Datablist. Você pode colar o JSON no editor ou fazer upload de um arquivo .json.

Para uma resposta pequena de API, colar o conteúdo funciona bem. Para uma exportação maior, prefiro fazer upload do arquivo, pois isso evita cortes acidentais ao copiar e colar. O conteúdo do arquivo é lido no navegador, e a conversão acontece localmente, sem que os dados sejam enviados aos servidores do Datablist para esse processamento.

Depois que o JSON é carregado, o Datablist analisa sua estrutura e procura arrays de objetos. Ele aceita raízes JSON que sejam arrays ou objetos e verifica caminhos aninhados como $.results, $.data.items ou arrays ainda mais profundos.

Quando o arquivo é difícil de entender, às vezes abro primeiro o JSON no JSONCrack. Ele exibe uma árvore visual que ajuda a encontrar o array que deve virar linhas. Essa etapa é opcional, mas útil quando o arquivo tem vários arrays possíveis.

Neste exemplo, o nó de linhas correto é:

$.results

Escolho $.results porque quero uma empresa por linha. Cada item desse array se torna uma linha do CSV.

O Datablist pode recomendar um nó de linhas, mas ainda assim faço uma verificação manual. É nesse ponto que ocorre a maioria dos erros de conversão. Um arquivo JSON pode conter um array principal de empresas, um array secundário de contatos e outro array secundário de tags ou eventos. Todos são arrays, mas apenas um corresponde ao CSV que você deseja criar.

⚠️ Mudar o nó de linhas muda o conjunto de dados

$.results e $.results[].contacts são nós de linhas válidos, mas não geram o mesmo CSV. Escolha o array principal quando quiser uma linha por conta. Escolha o array secundário quando os itens aninhados forem o conjunto de dados desejado.

Neste artigo, mantenho o nó de linhas principal:

• $.results significa uma empresa ou conta por linha.
• $.results[].contacts significaria um contato por linha.

A segunda opção também pode estar correta, mas altera o resultado. Um CSV no nível dos contatos é útil quando você quer uma lista de pessoas. Um CSV no nível das empresas é mais adequado para limpar contas, enriquecer empresas, importar registros para um CRM ou analisar métricas.

Escolher o nó de linhas correto

O nó de linhas é o array JSON cujos itens serão transformados nas linhas do CSV.

Os exemplos mais comuns são estes:

Antes de escolher, costumo fazer uma pergunta: o que cada linha deve representar?

Se cada linha deve representar uma empresa, conta, pedido, produto, anúncio ou evento, escolha o array principal. Se cada linha deve representar um contato, e-mail, item de pedido, preço, comentário ou evento secundário, escolha o array filho.

Parece simples, mas essa decisão muda todo o CSV.

Com $.results, o CSV mantém o contexto da empresa. O campo contacts permanece dentro da linha da empresa como um valor aninhado, a menos que você decida processar os contatos separadamente. Com $.results[].contacts, o CSV se torna uma lista de contatos, mas os campos da empresa principal não são incluídos automaticamente, a menos que o conversor adicione esse recurso em uma versão futura.

Por padrão, começo com o array principal. Ele gera uma primeira exportação mais segura, pois ainda posso analisar os arrays aninhados depois. Só mudo para um array filho quando os itens aninhados são o verdadeiro conjunto de dados.

Nivelar objetos JSON aninhados

É ao lidar com objetos aninhados que um conversor de CSV precisa oferecer mais do que uma simples transformação de arquivo.

No arquivo de exemplo, metrics é um objeto:

{
  "metrics": {
    "employees": 124,
    "revenue": {
      "amount": 476171,
      "currency": "USD"
    }
  }
}

Em uma planilha, não quero uma única célula metrics contendo um objeto JSON. Quero colunas que possam ser filtradas e ordenadas:

• employees
• amount
• currency

O Datablist detecta os caminhos de objetos aninhados e permite escolher quais deles serão nivelados. Mantenho os campos escalares úteis como colunas niveladas porque eles funcionam melhor em ferramentas que trabalham com CSV.

Neste exemplo, faço o seguinte nivelamento:

• metrics.employees em employees
• metrics.revenue.amount em amount
• metrics.revenue.currency em currency

O CSV esperado no nível das empresas tem esta aparência:

Prefiro nomes de colunas fáceis de ler na primeira exportação. Se o arquivo tiver nomes repetidos em objetos diferentes, confira a prévia antes de baixar. Por exemplo, billing.amount e revenue.amount não devem ser reduzidos à mesma coluna ambígua amount sem uma revisão.

💡 Minha configuração padrão para nivelamento

Nivele os campos escalares que você pretende filtrar, ordenar ou importar como colunas. Mantenha objetos ou arrays estruturados como JSON quando o nivelamento puder ocultar o significado ou criar células difíceis de ler.

Tratar arrays dentro das linhas JSON

Os arrays exigem uma decisão à parte porque células CSV armazenam texto, enquanto arrays JSON podem representar tipos diferentes de informação.

Uma lista de tags não é igual a uma lista de contatos. Uma lista de e-mails não é igual a uma lista de itens de pedido. Evito aplicar uma regra única quando os arrays têm significados diferentes.

Para o arquivo de exemplo, eu usaria estas configurações:

O Datablist oferece opções para tratar arrays, como unir valores, manter os arrays como strings JSON, usar apenas o primeiro item e definir configurações caso a caso.

Minha regra padrão é simples:

• Una arrays simples, como listas de tags.
• Mantenha arrays estruturados como strings JSON quando precisar preservá-los.
• Use apenas o primeiro item quando ele tiver um significado claro, como um e-mail principal.
• Mude o nó de linhas quando cada item do array merecer sua própria linha.

Na exportação de empresas, mantenho contacts como um valor estruturado porque cada contato tem nome, e-mails e telefones. Nivelar tudo em uma única célula deixaria o CSV confuso, enquanto manter apenas o primeiro contato causaria perda de dados.

Para uma exportação de contatos, eu selecionaria $.results[].contacts. O CSV passaria a conter colunas no nível dos contatos, como:

A contrapartida é a perda de contexto. A exportação de empresas mantém a linha completa de cada empresa. A exportação de contatos se concentra nas pessoas, mas os campos da empresa principal não são copiados automaticamente para cada linha de contato, a menos que a ferramenta passe a oferecer esse recurso em uma versão futura.

Configurar as opções de saída

Depois de acertar o nó de linhas, o nivelamento e as configurações dos arrays, ajuste a saída do CSV.

Normalmente, começo assim:

• Separador: vírgula para um CSV padrão.
• Linha de cabeçalho: ativada.
• Formato de data: manter o original, a menos que a planilha de destino exija um formato mais amigável.

Use ponto e vírgula como separador quando sua ferramenta de planilha ou configuração regional esperar arquivos separados por ponto e vírgula. Isso pode ser relevante em configurações europeias de planilhas, nas quais a vírgula costuma ser usada como separador decimal.

Para as datas, prefiro manter o formato de origem na primeira exportação. Se a origem usar timestamps ISO, eles serão fáceis de processar posteriormente e preservarão os dados de fuso horário. Se o CSV for destinado a um colega sem perfil técnico, formatar a data pode facilitar a leitura do arquivo.

Antes de baixar, confira as duas prévias:

• A prévia em tabela ajuda a inspecionar linhas e colunas.
• A prévia do CSV bruto ajuda a conferir separadores, aspas e quebras de linha.

🔑 Confira a prévia antes de exportar

É na prévia que você identifica um nó de linhas incorreto, colunas ausentes, arrays confusos e problemas com separadores. Prefiro dedicar 30 segundos a essa etapa do que corrigir depois uma importação com falhas em um CRM ou uma planilha.

Também confiro a prévia do CSV bruto quando há arrays ou textos com várias linhas. Isso leva poucos segundos e detecta uma quantidade surpreendente de problemas de importação.

Revisar e baixar o CSV

Antes de baixar, sigo esta checklist:

• O número de linhas corresponde ao nó selecionado?
• As linhas representam a entidade desejada?
• employees, amount e currency estão separados em colunas úteis?
• Os arrays estão legíveis ou foram preservados como JSON quando a estrutura é importante?
• Os valores nulos de receita estão em branco ou suficientemente claros para a próxima etapa?
• As datas estão adequadas para a planilha ou ferramenta de importação?
• A prévia do CSV bruto usa o separador esperado?

Em seguida, baixe o CSV. Quando você faz upload de um arquivo, o nome do arquivo baixado pode ser baseado no nome original, facilitando o rastreamento da origem do CSV.

Após a exportação, abra o arquivo no editor de CSV do Datablist, no Excel, no Google Sheets ou em sua próxima ferramenta de dados. No Datablist, você pode continuar com limpeza, filtragem, deduplicação, enriquecimento ou tradução. Se gerar várias exportações, poderá comparar dois arquivos CSV. Se o arquivo for grande demais para outra ferramenta, poderá dividir o CSV em arquivos menores.

Resultado esperado no CSV

Ao selecionar $.results, o resultado principal terá uma empresa ou conta por linha.

Ao selecionar $.results[].contacts, o resultado muda para um contato por linha.

As duas exportações são válidas, mas respondem a necessidades diferentes.

Use a exportação no nível das empresas para limpar contas, analisar dados firmográficos, enriquecer registros de empresas ou preparar importações para um CRM. Use a exportação no nível dos contatos quando as pessoas forem o conjunto de dados de interesse.

Quando usar este fluxo de trabalho

Este fluxo é útil sempre que o JSON for o formato de origem, mas o CSV for o formato usado no trabalho.

Alguns bons exemplos:

• Respostas de API com metadados, paginação e um array results aninhado.
• Resultados de scraping via API com anúncios, produtos, contatos ou eventos.
• Exportações de CRM e RevOps nas quais empresas contêm contatos, tags, métricas e campos personalizados.
• Exportações de marketplaces ou catálogos de produtos com variantes, preços, categorias e fornecedores.
• Logs de webhook nos quais os eventos estão aninhados em um payload.
• Fluxos de localização nos quais você deseja traduzir o CSV resultante.

O padrão é sempre o mesmo: encontre o array que representa as linhas, nivele os campos de objeto necessários, decida como tratar os arrays e confira a prévia antes de exportar.

Como resolver problemas na conversão de JSON em CSV

Se o JSON for inválido, verifique primeiro o arquivo de origem. Vírgulas ausentes, logs de console copiados, texto adicional no final, downloads incompletos e aspas sem escape podem impedir a análise. Normalmente, valido o arquivo antes de alterar as configurações de conversão, pois um JSON inválido precisa ser corrigido na origem.

Se nenhum nó de linhas for encontrado, talvez o arquivo não contenha um array de objetos. Um único objeto composto apenas por campos escalares não é suficiente para este fluxo. Raízes primitivas, strings, números e valores isolados não criam linhas CSV úteis.

Se as linhas erradas aparecerem na prévia, altere o nó de linhas selecionado. Isso geralmente significa que o conversor encontrou um array, mas não aquele que você tinha em mente. Procure o caminho em que os registros estão armazenados, como $.results, $.data.items ou $.payload.records.

Se contatos, tags, itens de pedido ou eventos estiverem difíceis de ler, ajuste o tratamento dos arrays. Una listas simples. Mantenha arrays estruturados como JSON quando quiser preservar os detalhes. Mude para um nó filho quando cada item aninhado precisar virar uma linha.

Se o processamento de um arquivo grande parecer lento, lembre-se de que o desempenho do navegador e do dispositivo ainda faz diferença. O Datablist executa a análise e a conversão em um web worker; portanto, o processamento não ocorre na thread principal da interface. Mesmo assim, a memória e a CPU locais continuam definindo os limites práticos.

Se o CSV não for importado corretamente em outra ferramenta, tente usar outro separador, mantenha a linha de cabeçalho ativada e analise a prévia do CSV bruto. Aspas e quebras de linha podem fazer diferença quando os valores JSON contêm textos, arrays ou objetos aninhados.

O que acontece no navegador

O Datablist analisa e converte o JSON em um worker do navegador. Esse worker identifica possíveis nós de linhas, armazena o objeto analisado em cache, converte o nó selecionado em CSV e devolve a prévia e o resultado para a interface.

Isso é importante por dois motivos.

Primeiro, o trabalho de conversão não acontece na thread principal da interface. Assim, a página continua responsiva enquanto o arquivo é analisado.

Segundo, o processamento ocorre localmente no navegador, sem que o arquivo seja enviado aos servidores do Datablist para conversão. Isso é útil quando você trabalha com exportações de API, resultados de scraping ou arquivos internos e não quer enviá-los a um conversor no servidor.

Ainda assim, siga as regras habituais de tratamento de dados. O processamento local no navegador é útil, mas não substitui as políticas de privacidade e compliance da sua empresa.

Conclusão

Converter JSON aninhado em CSV é, em grande parte, uma questão de escolher o nó de linhas correto. Depois de definir qual array deve virar linhas, o restante fica bem mais simples.

No arquivo de exemplo, $.results gera uma empresa por linha. Nivelar metrics.employees, metrics.revenue.amount e metrics.revenue.currency cria colunas úteis para a planilha. As configurações dos arrays determinam se campos como tags, website e contacts serão transformados em texto legível, preservados como JSON ou exportados separadamente no nível dos contatos.

Abra o conversor de JSON para CSV, faça upload de uma exportação JSON aninhada, selecione o nó de linhas, confira a prévia e baixe o CSV. Depois, abra o arquivo exportado no editor de CSV do Datablist se precisar fazer limpeza, filtragem, deduplicação, enriquecimento ou tradução.

FAQ

Como converter JSON aninhado em CSV?

Use um conversor que permita selecionar qual array JSON será transformado em linhas. No Datablist, cole ou faça upload do JSON, escolha o nó de linhas, nivele os campos úteis dos objetos aninhados, configure o tratamento dos arrays, confira a tabela e baixe o CSV.

Posso converter registros em results de JSON para CSV?

Sim. Selecione $.results como nó de linhas quando cada item dentro de results precisar se tornar uma linha do CSV.

Como converter data.items ou payload.records em CSV?

Escolha $.data.items ou $.payload.records como nó de linhas se esse caminho contiver os objetos que você deseja transformar em linhas. O caminho exato depende da estrutura do JSON.

Como nivelar campos JSON aninhados em colunas CSV?

Ative o nivelamento de caminhos de objetos aninhados, como metrics.revenue. Em seguida, confira as colunas geradas na prévia antes de exportar.

Como tratar arrays dentro das linhas JSON?

Una listas simples, como tags; mantenha arrays estruturados como strings JSON quando precisar preservá-los; ou escolha um nó de linhas mais profundo quando cada item do array precisar virar sua própria linha.

Posso converter um arquivo JSON grande em CSV online?

Sim, desde que o navegador e o dispositivo consigam processar o arquivo. O Datablist usa um web worker para a análise e a conversão, mas arquivos muito grandes ainda dependem do desempenho local.

Um conversor online de JSON para CSV é seguro?

O conversor do Datablist processa o arquivo localmente no navegador, sem enviá-lo aos servidores do Datablist para conversão. Mesmo assim, siga as regras de tratamento de dados da sua organização.

O que é um nó de linhas na conversão de JSON para CSV?

Um nó de linhas é o array JSON cujos itens se tornam linhas do CSV. Por exemplo, $.results cria uma linha do CSV para cada objeto dentro do array results.

O que acontece ao escolher $.results[].contacts em vez de $.results?

O CSV passa a ter uma linha por contato, em vez de uma linha por empresa ou conta. Os campos da empresa principal não são incluídos automaticamente, a menos que a ferramenta passe a oferecer esse recurso.

O que fazer depois de exportar o CSV?

Abra o arquivo no Datablist ou em outra ferramenta de planilhas para limpar, filtrar, deduplicar, enriquecer, traduzir ou importar os dados para outro sistema.