Converter XLSX para JSON

Esta conversão existe por causa de um padrão que se repete em toda organização: a versão oficial de alguma coisa — uma tabela de preço, um catálogo de produto, uma tabela de tradução, um horário de funcionamento, um mapeamento de código para nome — mora numa planilha mantida por alguém que não é programador, e precisa chegar a um programa que espera dado.

É um arranjo perfeitamente razoável. Uma planilha é uma boa interface de edição, o pessoal de negócio já sabe usar, e construir uma ferramenta administrativa pequena para substituir ela raramente vale o esforço. O que falta é uma conversão confiável na fronteira, e é esse o trabalho inteiro aqui.

O mapeamento é o óbvio. A primeira linha é tratada como cabeçalho e fornece o nome das chaves; toda linha depois dela vira um objeto; toda célula vira um valor nesse objeto. O resultado é um vetor de registros, o formato que um programa consumidor quase sempre quer.

Vale pensar no cabeçalho de propósito, porque essas células viram nome de chave no seu código. Curto, minúsculo, sem espaço e sem pontuação produz chaves agradáveis de trabalhar; um cabeçalho como «Preço unitário (R$, sem imposto)» produz algo que ninguém quer digitar duas vezes.

Uma planilha não guarda data como data. Guarda um número contando dias a partir de uma origem, e a formatação da célula é o que faz 45678 aparecer como uma data na tela. Converter devolve o que de fato está no arquivo, que é o número.

As duas formas de contornar isso são deliberadas. Formate a coluna como texto na planilha e digite data ISO nela, o que torna o arquivo autodescritivo e sobrevive a qualquer conversão. Ou transforme os valores depois da conversão, aplicando a aritmética de contagem de dias você mesmo. As duas funcionam; descobrir o problema depois que o dado chega em produção não funciona.

Um CEP, um código de produto, um código bancário ou um identificador nacional guardado numa célula formatada como número já perdeu os zeros à esquerda — o Excel fez isso quando o valor foi digitado ou importado, e o arquivo contém um número.

O mesmo vale para identificador acima de quinze dígitos, que perde os últimos dígitos para ponto flutuante dentro da própria planilha. Nenhum conversor recupera nenhum dos dois, porque a informação não está no arquivo. A correção fica a montante: essas colunas precisam ser formatadas como texto na planilha, e vale avisar quem mantém a planilha uma vez em vez de consertar a saída todo mês.

Fórmula, e você recebe o resultado dela — que é o que se quer, já que um programa não tem o que fazer com uma fórmula. Formatação, cor, regra condicional e largura de coluna, nada disso é dado. Gráfico, comentário e célula mesclada, sem equivalente nenhum.

Célula mesclada é a que vale observar. Um cabeçalho mesclado abrangendo três colunas é um recurso de apresentação, e produz um objeto com uma chave preenchida e duas vazias — um registro de aparência estranha vindo de uma planilha de aparência perfeitamente sensata. Cabeçalho plano, uma célula por coluna, é o que torna esta conversão sem graça, e sem graça é o objetivo.

O arranjo comum é manter a planilha como origem editável, converter para JSON como uma etapa, e versionar o JSON junto do código. O dado fica então revisável num pull request, versionado, e disponível no momento do build sem nenhuma dependência de tempo de execução num arquivo que alguém pode mover.

Dois hábitos fazem isso funcionar ao longo do tempo. Converta sempre do mesmo jeito, para uma diferença mostrar mudança real em vez de reordenação. E valide o resultado contra um esquema antes de versionar, para uma coluna renomeada por um colega bem-intencionado falhar uma checagem em vez de produzir objetos com um campo faltando em silêncio.

Se o destino é uma importação de banco de dados, uma ferramenta de análise ou um pipeline de dados, o CSV costuma ser o intermediário melhor: transmite em fluxo, todo sistema lê, e não impõe uma estrutura de aninhamento a um dado que não tem nenhuma.

O JSON ganha o lugar dele quando o dado vai para código de aplicação — um front-end, um arquivo de configuração, um fixture de API — onde um vetor de objetos é o que a linguagem quer e a análise é uma linha. Escolha pelo que lê o arquivo, não por qual formato é mais moderno.

A conversão roda na aba do navegador, no seu próprio processador, então nada é enviado e nenhum servidor guarda cópia. Não há conta, não há fila, não há cota diária; o limite de tamanho é 100 MB por arquivo, cem arquivos por lote.

Isso não é incidental aqui. As planilhas que as pessoas convertem são internas: preço, margem, lista de cliente, registro de funcionário, catálogo ainda não lançado. Não enviar elas a lugar nenhum é a forma mais simples de não precisar confiar isso a ninguém.