Conversor de CSV para JSON

O que faz esta página

Esta página converte ficheiros CSV — dados tabulares separados por vírgulas, pontos e vírgulas ou tabuladores — para JSON, produzindo normalmente uma matriz de objetos onde cada linha se torna um objeto e cada coluna uma chave. O processo é direto: arrasta-se ou seleciona-se o ficheiro a partir do dispositivo, escolhe-se “JSON” como formato de saída, indica-se o delimitador correto caso o CSV use algo diferente da vírgula, e a ferramenta mostra uma pré-visualização do resultado antes da transferência do ficheiro JSON final.

A ferramenta, no entanto, faz muito mais do que uma simples tradução de formatos. Ela lida com os problemas reais que surgem quando se trabalha com CSV, um formato antigo e frágil, e com JSON, um formato moderno e estruturado. O ficheiro de entrada pode ser CSV, JSON ou XLSX — se o utilizador carregar JSON ou XLSX, a ferramenta interpreta-os primeiro como tabelas, mas o cenário principal da página é mesmo CSV para JSON.

Diferenças fundamentais face a outras conversões

O que torna esta página diferente de outras ferramentas de conversão de formatos assenta em quatro pontos que resultam diretamente da natureza do CSV e do JSON.

Sem tipos, só texto. O CSV guarda tudo como texto plano. Cada campo é uma sequência de carateres, sem qualquer indicação de que seja um número, uma data, um booleano ou um valor nulo. Já o JSON suporta esses tipos de forma nativa. A conversão, porém, não infere tipos: todos os campos do CSV permanecem como cadeias de texto no JSON de saída. Isto significa que preços, quantidades, datas e códigos postais com zeros à esquerda chegam ao JSON como strings. Se precisar de os tratar como inteiros ou números de ponto flutuante, terá de os converter manualmente depois do download.

Sem aninhamento possível. O CSV é estritamente uma tabela plana. Cada linha tem o mesmo número de colunas (ou devia ter) e não existe qualquer noção de objetos dentro de objetos. A conversão produz, por isso, uma matriz plana de objetos planos. Não é possível gerar JSON hierárquico — objetos dentro de objetos a partir de um CSV — sem regras adicionais que a ferramenta não aplica. (No sentido inverso, de JSON para CSV, é necessário achatar estruturas aninhadas.)

O delimitador é crítico. Diferente das páginas irmãs que trabalham com JSON ou Excel, aqui o utilizador tem de especificar se o CSV usa vírgulas, pontos e vírgulas ou tabuladores. Se o delimitador estiver errado, a tabela fica desfeita: uma linha com campos que contêm vírgulas será interpretada como várias colunas em vez de uma só.

Vírgulas e quebras de linha embebidas são frágeis. O CSV possui regras de citação (uso de aspas duplas) para permitir campos com vírgulas ou quebras de linha. Na prática, estas regras são frequentemente ignoradas ou mal implementadas. Ficheiros exportados por diferentes programas respeitam-nas com graus variados. Isto faz com que a conversão de CSV para JSON seja particularmente sensível a erros de análise, mais do que outras transformações de formato.

Como funciona o processo de conversão

O utilizador começa por escolher um único ficheiro. A ferramenta deteta automaticamente o formato de entrada — CSV, JSON ou XLSX — e, se for CSV, apresenta a opção de selecionar o delimitador entre vírgula, ponto e vírgula ou tabulador. A escolha correta é essencial porque o separador define como as colunas são divididas.

De seguida, a ferramenta analisa o conteúdo, ignorando formatação (inexistente em CSV) e sem executar quaisquer fórmulas. Os dados visíveis são convertidos linha a linha. Cada cabeçalho na primeira linha do CSV (se existir) torna-se uma chave no objeto JSON; cada valor na linha seguinte torna-se o valor dessa chave, sempre como string.

Durante a análise, a ferramenta constrói uma pré-visualização que mostra o resultado já convertido, o número de linhas e colunas da tabela, e o tamanho do ficheiro de saída. O utilizador pode confirmar que a conversão está correta antes de transferir o ficheiro JSON final.

Uma nota importante sobre quebras de linha: se o CSV contiver campos entre aspas com quebras de linha no interior, estas são preservadas no valor JSON como \n. Isto é útil para campos de texto longo, como descrições ou moradas, mas requer atenção se o JSON for depois consumido por um sistema que não espere quebras de linha dentro de strings.

Limitações e erros comuns

A ferramenta impõe limites e trata erros previsíveis com mensagens claras, todas apresentadas ao utilizador na interface.

Condições de erro e respetivas mensagens

Problemas comuns de análise

Citação mal formada. Muitos CSVs utilizam aspas para envolver campos que contêm vírgulas, mas as regras oficiais (RFC 4180) nem sempre são seguidas. Aspas não escapadas, ou aspas a abrir sem fechar, quebram a análise. A ferramenta deteta estas situações e exibe a mensagem de erro correspondente.

Número inconsistente de colunas. Se uma linha tiver mais ou menos campos que o cabeçalho, a tabela fica desalinhada. A ferramenta tenta interpretar, mas se a inconsistência for grave, o CSV não é analisável.

Zeros à esquerda. Como todos os campos são tratados como texto, zeros à esquerda em códigos postais, códigos de produto ou identificadores são preservados na íntegra. No entanto, se depois carregar o JSON num ambiente que faça conversão automática de tipos (como JavaScript com JSON.parse() seguido de operações numéricas), esses zeros podem perder-se. O utilizador deve estar consciente de que a responsabilidade de manter a integridade dos zeros à esquerda passa para o código que consumir o JSON.

Quebras de linha não citadas. Um campo CSV com uma quebra de linha mas sem aspas é interpretado como o fim de uma linha e o início da seguinte, partindo a tabela em duas linhas erradas. A ferramenta não consegue corrigir este erro, pois não existe forma de distinguir sem as regras de citação.

Para quem é esta ferramenta

A página serve um conjunto específico de utilizadores, todos com o denominador comum de precisar de transformar dados tabulares planos em JSON sem depender de um servidor ou de software instalado.

• Um programador que recebeu uma exportação CSV de uma base de dados ou folha de cálculo e precisa de alimentar uma aplicação JavaScript ou uma API que espera JSON. Em vez de escrever um script ad hoc, carrega o ficheiro, confere a pré-visualização e transfere o resultado.
• Um analista de dados que quer converter um ficheiro CSV antigo de moradas — com códigos postais a começar por zero — para JSON, mantendo esses zeros intactos. A ferramenta trata todos os campos como texto, pelo que a integridade dos zeros está garantida.
• Uma equipa que partilha dados entre um colega não técnico (que trabalha em Excel/CSV) e uma stack tecnológica que só fala JSON, sem ter de carregar informação sensível para um servidor externo. A conversão decorre inteiramente no navegador.
• Qualquer pessoa que precise de preparar uma tabela simples de produtos, contactos ou registos para usar numa ferramenta web que lê JSON, como uma aplicação de visualização ou um dashboard.
• Um estudante ou investigador que precisa de transformar um CSV único num formato estruturado para um trabalho de programação, sem se preocupar com instalação de bibliotecas ou configuração.

Perguntas Frequentes

O JSON gerado contém os números como números ou como texto?

Todos os valores do JSON são strings. Se um campo CSV contiver 1234, no JSON aparecerá "1234". A ferramenta não infere tipos. Se precisar que o valor seja um número, terá de o converter manualmente no código que consome o JSON, por exemplo com Number() ou parseInt().

Posso converter um ficheiro JSON de volta para CSV na mesma página?

A página está desenhada para a direção CSV → JSON. Existe uma página irmã para a conversão inversa, mas aqui o formato de saída é sempre JSON. O ficheiro de entrada pode ser CSV, JSON ou XLSX, mas se carregar JSON, a ferramenta interpreta-o como uma tabela (achatando objetos aninhados) e depois converte-o para JSON outra vez — o que pode parecer redundante, mas permite ver a estrutura plana resultante.

O que acontece se o CSV tiver aspas dentro de um campo?

Se as aspas estiverem corretamente escapadas (duas aspas consecutivas representam uma aspa literal), a ferramenta trata-as bem. Se as aspas não estiverem escapadas (por exemplo, um campo como "o livro "A Ilha" é bom"), a análise falha e a mensagem "Este CSV não pôde ser analisado." é exibida.

Porque é que a pré-visualização mostra sempre o mesmo número de linhas e colunas, mas o ficheiro parece diferente?

A pré-visualização reflete o JSON após a conversão. Se o CSV tiver linhas em branco ou campos com quebras de linha internas, essas quebras são preservadas como \n no JSON. A pré-visualização pode limitar o número de linhas exibidas por razões de desempenho, mas o ficheiro transferido contém todos os dados.

O meu ficheiro CSV tem cabeçalhos. E se não tiver cabeçalhos?

A ferramenta assume que a primeira linha do CSV contém os cabeçalhos, que se tornam as chaves dos objetos JSON. Se o CSV não tiver cabeçalho, a ferramenta ainda tenta analisar, mas as chaves serão indefinidas ou serão usados nomes genéricos (como "coluna1", "coluna2"), dependendo da implementação. O melhor é garantir que o CSV tem uma linha de cabeçalho ou, em alternativa, editá-lo antes de carregar.

A ferramenta guarda o meu ficheiro no servidor?

Não. A conversão é feita inteiramente no navegador, sem qualquer envio dos dados para um servidor. O ficheiro nunca sai do seu dispositivo. Isto é importante para proteger dados sensíveis ou confidenciais contidos em ficheiros CSV de clientes, fornecedores ou privados.