XLS
Objetivo
O conector XLS tem como objetivo permitir o processamento, transformação e modernização de arquivos de planilha legados no formato Excel 97-2003 (.xls / OLE2).
Principais cenários de uso:
- Modernização de dados legados: Conversão direta de relatórios antigos .xls para o formato moderno .xlsx.
- Extração de dados tabulares: Leitura de planilhas .xls e transformação direta em coleções organizadas em formato JSON para alimentação de fluxos de trabalho e bancos de dados.
- Automação de processos financeiros e contábeis: Processamento automático de extratos e relatórios gerados por sistemas legados.
- Suporte flexível de entrada e saída: Leitura via arquivos físicos na pasta temporária ou via conteúdos codificados em Base64 / Data URIs.
Recurso: Conversão
O recurso de Conversão agrupa todas as ações destinadas a transformar arquivos no formato .xls para formatos estruturados (JSON) ou modernos (XLSX).
Operação: Converter para JSON
Permite extrair os dados contidos em uma aba do arquivo .xls e transformá-los diretamente em uma estrutura de dados JSON.
Parâmetros da operação
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Tipo de conversão | object | Sim | Origem da planilha .xls (Base64 ou Arquivo na Pasta Temporária). |
Nome da Planilha | string | Não | Nome da aba (sheet) que será convertida. Se omitido, converte a primeira aba (Sheet1). |
Tratar cabeçalhos | boolean | Não | Define se a primeira linha será usada como chave dos objetos. Padrão: true. |
Opções do Tipo de Conversão
Opção | Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Base64 | Valor de Entrada | string | Sim | Conteúdo do arquivo .xls codificado em Base64 (ou Data URI). |
Arquivo na Pasta Temporária | Nome do Arquivo | string | Sim | Nome do arquivo .xls previamente salvo no /tmp (ex: file.xls). |
Tratamento de Cabeçalhos (header)
- Habilitado (true): A primeira linha é tratada como cabeçalho. A resposta retornará um Array de Objetos no formato [{"Coluna1": "Valor1", "Coluna2": "Valor2"}].
- Desabilitado (false): A resposta retornará uma matriz com todas as linhas brutas no formato de Array de Arrays [["Coluna1", "Coluna2"], ["Valor1", "Valor2"]].
Seleção de Aba (sheet_name): Caso o campo Nome da Planilha seja deixado em branco, o conector identificará e converterá automaticamente a primeira aba contida no arquivo .xls.
Exemplo de Resposta (com header: true)
Operação: Converter para XLSX
Permite converter uma planilha legada no formato .xls para o formato moderno .xlsx (OpenXML).
Parâmetros da operação
Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Tipo de Conversão | object | Sim | Origem da planilha .xls (Base64 ou Arquivo na Pasta Temporária). |
Nome da Planilha | string | Não | Nome da aba que será convertida. Se omitido, converte a primeira aba (Sheet1). |
Salvar na Pasta Temporária | object | Não | Define se o resultado .xlsx será salvo no /tmp ou retornado em Base64. |
Tratar cabeçalhos | boolean | Não | Define se a primeira linha será usada como cabeçalho. Padrão: true. |
Opções do Tipo de Conversão
Opção | Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Base64 | Valor de Entrada | string | Sim | Conteúdo do arquivo .xls codificado em Base64 (ou Data URI). |
Arquivo na Pasta Temporária | Nome do Arquivo | string | Sim | Nome do arquivo .xls previamente salvo no /tmp (ex: file.xls). |
Opções de Salvar na Pasta Temporária (save_to_tmp)
Opção | Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Sim | Nome do Arquivo | string | Sim | Nome do arquivo .xlsx que será salvo na pasta temporária (ex: file.xlsx). |
Não | (Nenhum) | - | - | O arquivo retornado será disponibilizado diretamente em Base64 na resposta. |
Salvar na Pasta Temporária vs. Retorno em Base64
- Sim (_true): O arquivo .xlsx gerado é gravado diretamente no diretório temporário do servidor (/tmp/{flowExecID}/), otimizando a memória durante a execução do fluxo. A resposta conterá os metadados do arquivo gerado:{ "success": true, "file_name": "relatorio.xlsx", "message": "XLSX file created successfully in temporary folder!" }
- Não (_false): O arquivo .xlsx gerado é convertido para Base64 e retornado no corpo da resposta da operação:{ "success": true, "file_name": "relatorio.xlsx", "base64": "UEsDBBQABgAIAAAAIQ...", "message": "XLSX file created successfully!" }
Na Prática
Converter para JSON
- Converter arquivo .xls da pasta temporária para JSON com cabeçalho:
- Tipo de Conversão: Arquivo na Pasta Temporaria
- Nome do Arquivo: extrato.xls
- Tratar cabeçalhos: true
- Converter conteúdo Base64 de arquivo .xls para JSON (sem cabeçalho):
- Tipo de Conversão: Base64
- Valor de Entrada: data:application/vnd.ms-excel;base64,0M8R4KGxGuE...
- Tratar cabeçalhos: false
Converter para XLSX
- Converter .xls em Base64 e salvar no /tmp como dados.xlsx:
- Tipo de Conversão: Base64
- Valor de Entrada: 0M8R4KGxGuE...
- Salvar na Pasta Temporária: Sim
- Nome do Arquivo: dados.xlsx
- Converter .xls da pasta temporária e receber o Base64 na resposta:
- Tipo de Conversão: Arquivo na Pasta Temporaria
- Nome do Arquivo: relatorio_antigo.xls
- Salvar na Pasta Temporária: Não
Observações Finais
- Formato Legado: O conector é específico para o formato binário Excel 97-2003 (.xls). Para manipulação nativa de planilhas modernas, utilize o conector XLSX.
Conclusão
O conector XLS oferece a flexibilidade necessária para transformar planilhas legadas em fontes de dados estruturadas ou formatos modernos, permitindo que sua aplicação interaja com relatórios antigos de forma inteligente, rápida e segura.