--- title: XLS slug: xls docTags: createdAt: 2025-08-15T14:54:59.452Z --- ## 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). | :::hint{type="info"} **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"]]. ::: :::hint{type="warning"} **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)** :::BlockQuote \[ \{ "ID": "1", "Nome": "Alice", "Cargo": "Desenvolvedora" }, \{ "ID": "2", "Nome": "Bob", "Cargo": "Arquiteto" } ] ::: ### 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. | :::hint{type="info"} **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.