--- title: XLSX slug: xlsx docTags: createdAt: 2025-08-15T14:54:59.452Z --- ## Objetivo O conector **XLSX** permite ler e transformar arquivos `.xlsx` em JSON diretamente em fluxos da Fluid. Não requer autenticação nem conexão. É útil para manipular planilhas recebidas por FTP, SFTP, APIs ou arquivos base64. Não há documentação externa vinculada, pois o processamento é feito internamente pela Fluid. ## Criando um fluxo 1. Acesse o ambiente de fluxos na Fluid. 2. Adicione um novo passo e selecione o conector **XLSX**. 3. Escolha uma das operações disponíveis. ## Criando conexão Este conector **não requer conexão**. ## Configurando fluxo O conector possui duas operações principais para leitura de arquivos `.xlsx`: ## Recursos e Operações ### Recurso: XLSX ### Operação: Converter XLSX para JSON de origem FTP/SFTP **Descrição:** Selecione esta operação para transformar um arquivo `.xlsx` já carregado na memória (via FTP/SFTP ou outro passo anterior) em um objeto JSON. **Campos requeridos:** - `file_name` (string): Nome do arquivo `.xlsx`. Ex: `financeiro.xlsx`. **Campos opcionais:** - `header` (boolean): Informe se sua planilha possui cabeçalho. - `sheet_name` (string): Nome da aba a ser convertida. *** ### Operação: Converter XLSX em base64 para JSON **Descrição:** Transforme diretamente um conteúdo `.xlsx` codificado em base64 para JSON. **Campos requeridos:** - `base64` (string): Conteúdo base64 do arquivo `.xlsx`. **Campos opcionais:** - `header` (boolean): Informe se sua planilha possui cabeçalho. - `sheet_name` (string): Nome da aba a ser convertida. *** ### Operação: Criar arquivo A operação `Criar arquivo XLSX` do conector XLSX permite criar um arquivo Excel (.xlsx) a partir de dados JSON e retorna o arquivo gerado em formato base64. Esta operação é útil para gerar relatórios, planilhas e outros documentos estruturados a partir de dados dinâmicos. **Parâmetros de Entrada** A operação `Criar arquivo XLSX` requer os seguintes parâmetros: **Campos Obrigatórios** | Campo | Tipo | Descrição | | ----------------- | ------ | ------------------------------------------ | | `Nome do arquivo` | string | Nome do arquivo XLSX a ser criado | | `template` | string | Dados JSON que serão convertidos para XLSX | **** **Campos Opcionais** | Campo | Tipo | Descrição | | ---------------------------- | ------- | --------------------------------------------------------- | | `Nome da página` | string | Nome da página (padrão: "Sheet1") | | `Salvar na Pasta temporária` | boolean | O arquivo salvo na pasta temporária da execução do fluxo. | :::hint{type="info"} **Salvar na Pasta Temporária: **Quando habilitado, o arquivo XLSX será criado na pasta temporária do servidor e estará disponível para passos subsequentes do fluxo. Caso desabilitado, o conteudo base64 do arquivo será retornado diretamente na resposta da operação, permitindo que seja armazenado em variáveis ou enviado para outros sistemas sem a necessidade de criar um arquivo físico. ::: **Exemplo de JSON de Entrada** Criando XLSX com dados de objetos (recomendado) ```json [ {"nome": "João", "idade": 30, "salario": 5000}, {"nome": "Maria", "idade": 25, "salario": 4500} ] ``` Criando XLSX com dados de array simples ```json [ ["Nome", "Idade", "Salário"], ["João", 30, 5000], ["Maria", 25, 4500] ] ``` **Exemplo de JSON de Saída** Resposta de Sucesso ```json { "success": true, "file_name": "relatorio_vendas.xlsx", "base64": "UEsDBBQACAgIAKxRVVkAAAAAAAAAAAAAAAABAAAAeGwvd29ya2Jvb2sueG1spJTPS8MwFMfv...", "message": "XLSX file created successfully!" } ``` ### Operação: Leitura Paginada A operação **Leitura Paginada** (`readPage`) do conector XLSX permite converter um arquivo `.xlsx` em JSON de forma paginada, ou seja, lendo apenas um intervalo específico de linhas da planilha. Isso é especialmente útil para processar arquivos grandes de forma segmentada, evitando sobrecarga de memória e permitindo o tratamento dos dados em lotes. :::BlockQuote **Conector base:** `xlsx@v1` **Operação:** `readPage` ::: **Parâmetros gerais** | Parâmetro | Tipo | Obrigatório | Descrição | | ------------ | --------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | `operation` | `string` | Sim | Deve ser `readPage`. | | `sheet_name` | `string` | Não | Nome da página (aba) da planilha que será convertida. Caso não informado, será feita a conversão da primeira página. | | `header` | `boolean` | Não | Informe se sua planilha possui cabeçalho. Quando `true`, a primeira linha será tratada como cabeçalho. | | `start_row` | `string` | Não | A partir de qual linha a leitura deve começar (Ex: `1`). | | `end_row` | `string` | Não | Em qual linha a leitura deve parar. Deixe em branco ou `0` para ler até o fim do arquivo. | **Entrada XLSX** A operação `readPage` suporta **dois formatos de entrada** para o arquivo XLSX. Você deve escolher um deles: **Opção 1 — Base64 (**`useBase64`**)** Utilize esta opção quando o conteúdo do arquivo XLSX estiver disponível em formato Base64 (por exemplo, recebido via API ou extraído de outra integração). | Parâmetro | Tipo | Obrigatório | Descrição | | --------- | -------- | ----------- | -------------------------- | | `base64` | `string` | Sim | Base64 do arquivo `.xlsx`. | **Opção 2 — Path (**`usePath`**)** Utilize esta opção quando o arquivo XLSX estiver disponível em cache, inserido por um passo anterior do fluxo (ex.: FTP, SFTP, etc.). | Parâmetro | Tipo | Obrigatório | | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | `file_name` | `string` | Sim. Nome do arquivo com extensão. Exemplo: `financeiro.xlsx`. Nota: Arquivo inserido em cache por um passo anterior. | **Exemplos:** **Exemplo 1 — Leitura paginada com Base64** Neste exemplo, o arquivo é fornecido em Base64 e a leitura é feita das linhas 1 a 100, com tratamento de cabeçalho habilitado. ```json { "connector_base": "xlsx@v1", "operation": "readPage", "sheet_name": "Planilha1", "header": true, "base64": "{{.body.arquivo_base64}}", "start_row": "1", "end_row": "100" } ``` **Exemplo 2 — Leitura paginada com Path (arquivo em cache)** Neste exemplo, o arquivo foi inserido em cache por um passo anterior (ex.: download via FTP) e a leitura é feita das linhas 50 a 150, sem tratamento de cabeçalho. ```json { "connector_base": "xlsx@v1", "operation": "readPage", "sheet_name": "", "header": false, "file_name": "financeiro.xlsx", "start_row": "50", "end_row": "150" } ``` **Exemplo 3 — Leitura paginada até o final do arquivo** Quando o parâmetro `end_row` é deixado em branco ou com valor `0`, a leitura será feita a partir da `start_row` até a última linha da planilha. ```json { "connector_base": "xlsx@v1", "operation": "readPage", "sheet_name": "", "header": true, "file_name": "relatorio.xlsx", "start_row": "200", "end_row": "0" } ``` *** ### Operação: Adicionar Aba (*Append Sheet*) A operação `appendSheet` permite **adicionar uma nova aba (planilha)** a um arquivo XLSX existente no diretório temporário do fluxo. Além de criar a aba, a operação permite opcionalmente populá-la com dados estruturados (JSON) no momento da criação. Essa funcionalidade é ideal para organizar relatórios em múltiplas abas de forma dinâmica e eficiente. **Parâmetros de Entrada** | Parâmetro | Campo Técnico | Tipo | Obrigatório | Descrição | Exemplo | | ---------------------- | ------------- | --------------- | ----------- | --------------------------------------------------------------------------------------- | ---------------------------------- | | **Nome da Página** | `sheet_name` | `string` | **Sim** | O nome que será atribuído à nova aba dentro do arquivo. | `Faturamento_Q2` | | **Nome do Arquivo** | `file_name` | `string` | **Sim** | O nome do arquivo Excel original que já se encontra no diretório temporário do fluxo. | `relatorio_mensal.xlsx` | | **Conteúdo da Página** | `body` | `string` (JSON) | Não | Array de objetos JSON para popular a nova aba. Se omitido, a aba será criada em branco. | `[{"Produto": "A", "Valor": 120}]` | *** ### Operação: Adicionar novas linhas em uma página existente A operação permite **adicionar novas linhas** ao final de uma página existente em um arquivo XLSX, mantendo toda a estilização original da planilha (como cores, fontes, bordas e células mescladas) intacta. O conector identifica automaticamente a última linha preenchida com conteúdo real e insere os novos dados logo abaixo, evitando pular linhas em branco ou criar espaços vazios indesejados. **Parâmetros** | Parâmetro | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | ----------------------------------------------------------------------- | | Nome da página | string | **Sim** | O nome da página da planilha que receberá os novos dados. Ex: Sheet1. | | Nome do Arquivo | string | **Sim** | O nome do arquivo XLSX que já existe no seu fluxo (ex: relatorio.xlsx). | Os dados a serem inseridos devem ser passados através de **Template**, em formato JSON de matriz (array de arrays). Cada item representa uma linha a ser adicionada: **Exemplo de Preenchimento (Template)** :::BlockQuote \[ \["Maria Souza", 25, 4500], \["João Silva", 30, 6000] ] ::: **Dicas e Boas Práticas** - **Sequência do Fluxo:** Essa operação exige que o arquivo XLSX especificado no "Nome do Arquivo" já tenha sido gerado ou recebido por algum passo anterior do seu fluxo (por exemplo, baixado de um e-mail ou gerado pelo passo de "Criar arquivo XLSX"). - **Validação de Conteúdo:** O campo **Conteúdo** aceita estritamente uma lista de linhas no formato acima. Se o template for preenchido com um JSON inválido ou ficar vazio, o passo retornará um erro para garantir a consistência das informações. *** ### Observações - Os valores de `start_row` e `end_row` são do tipo `string`, mas devem conter valores numéricos. - Quando `header` é `true`, a primeira linha da planilha será utilizada como chave nos objetos JSON de saída. Caso contrário, os dados serão retornados em formato de array. - Se `sheet_name` não for informado, a conversão será realizada na **primeira página** da planilha. - Esta operação é ideal para cenários de **processamento em lotes**, onde o volume de dados do arquivo é grande e precisa ser dividido em múltiplas execuções. *** ## Formatos de Dados Suportados ### 1. Array de Objetos (Recomendado) Quando os dados são um array de objetos, as chaves do primeiro objeto são usadas como cabeçalhos da planilha: **Entrada:** ```json [ {"nome": "João", "idade": 30, "salario": 5000}, {"nome": "Maria", "idade": 25, "salario": 4500} ] ``` **Resultado na planilha:** | nome | idade | salario | | ----- | ----- | ------- | | João | 30 | 5000 | | Maria | 25 | 4500 | ### 2. Array de Arrays Para dados tabulares simples onde você controla completamente a estrutura: **Entrada:** ```json [ ["Nome", "Idade", "Salário"], ["João", 30, 5000], ["Maria", 25, 4500] ] ``` **Resultado na planilha:** | Nome | Idade | Salário | | ----- | ----- | ------- | | João | 30 | 5000 | | Maria | 25 | 4500 | ### 3. Objeto Único Um objeto único será convertido em uma linha com suas chaves como cabeçalhos: **Entrada:** ```json {"produto": "Notebook", "preco": 2500, "estoque": 15} ``` **Resultado na planilha:** | produto | preco | estoque | | -------- | ----- | ------- | | Notebook | 2500 | 15 | ## Na prática Neste tópico iremos criar um fluxo de conversão de um `.xlsx` em json via tráfego em base64 (muito comum o tráfego desses tipos de arquivos via api's) ![](https://api.archbee.com/api/optimize/Qjts8Bv3CHxMqFdbwM-Ig/SYOPwI9RC9k_EzO3QOWXw_image.png) ### Passo 'convert' Assim ficará a `Parametrização` do nosso primeiro e único passo: ::Image[]{src="https://api.archbee.com/api/optimize/Qjts8Bv3CHxMqFdbwM-Ig/K5SthOCQAVA_vX6t48wmt_image.png" size="60" width="428" height="510" position="center" darkWidth="428" darkHeight="510" showCaption="false"} Na aba `Propriedades` informamos o nome do passo: ::Image[]{src="https://api.archbee.com/api/optimize/Qjts8Bv3CHxMqFdbwM-Ig/XxPNlC0rAscdYGuUdLbKg_image.png" size="70" width="422" height="564" darkWidth="422" darkHeight="564" position="center" showCaption="false"} ### Disparo do fluxo Com o passo configurado basta disparar o fluxo sem a necessidade de informar um payload de entrada: ![](https://images.archbee.com/G1NTw6yAi4RDUYbsU8csp/ybQkjFba5dNGPdCwiKlcS_image.png?format=webp) Após o disparo, o resultado do fluxo aparecerá em realtime no canvas: ![](https://api.archbee.com/api/optimize/Qjts8Bv3CHxMqFdbwM-Ig/LgFOkYyLun3Op1DIVWvvB_image.png) Ao clicar em detalhes, temos a planilha no formato json convertida pelo conector XLSX: ![](https://api.archbee.com/api/optimize/Qjts8Bv3CHxMqFdbwM-Ig/FGHJlp0SEt4rzJe2yLokD_image.png) ## Observações adicionais - O conteúdo convertido retorna um array de objetos JSON, onde cada linha da planilha representa um item. - Em caso de erro na leitura (arquivo inválido, base64 malformado, aba inexistente), o passo falhará e poderá ser tratado com blocos de erro padrão. ## Conclusão O conector **XLSX** é uma solução rápida e sem autenticação para transformar planilhas em dados estruturados dentro dos fluxos da Fluid. Ideal para pipelines de integração que envolvem dados tabulares.