Excel Reader

1. Visão Geral

O componente Excel Reader (excel-reader) lê um arquivo Excel (.xlsx) linha por linha, sem carregar o arquivo inteiro na memória de uma vez. Isso torna possível processar planilhas grandes sem travar ou consumir memória excessiva.

Use quando o fluxo precisa importar dados de uma planilha Excel recebida (por exemplo, em um upload) e executar uma ação para cada linha, como cadastrar registros em um sistema.

Não é indicado para arquivos que não sejam Excel .xlsx, nem para casos em que os dados já vêm em JSON — nesse caso um ForEach comum é suficiente.

2. Pré-requisitos

• O arquivo Excel precisa estar disponível na mensagem antes deste componente rodar (por exemplo, resultado de um upload anterior no fluxo).
• Formato aceito: arquivo binário (.xlsx), disponibilizado como arquivo (File) ou como sequência de bytes (byte[]) dentro da mensagem.

3. Autenticação e Conexão

Não aplicável — este componente não se conecta a sistemas externos, apenas lê um arquivo já presente na mensagem.

4. Configuração / Operações Suportadas

O componente tem uma única operação: ler a planilha e, opcionalmente, executar um sub-fluxo para cada linha lida.

Campo	Obrigatório	Tipo	Descrição	Exemplo
fileName	Sim	Expressão	Nome da propriedade na mensagem onde o arquivo Excel está armazenado.	"arquivoUpload"
sheetName	Não	Expressão	Nome da aba específica a ser lida. Se não informado, a primeira aba encontrada é usada.	"Planilha1"
step	Não	Sub-fluxo	Sequência de componentes executada para cada linha lida da planilha.	Um passo que grava cada linha em um banco de dados
firstRow	Não	Número	Número da primeira linha de dados a considerar (ignora cabeçalhos acima dela). Valor padrão: 1.	2 (para pular uma linha de cabeçalho)
isAggregatedResult	Não	Texto ("true"/"false")	Se true, o resultado final traz o corpo de resposta de cada linha processada. Se false (padrão), traz apenas contadores de linhas processadas, com sucesso e com erro.	"true"

Cada linha lida é entregue ao sub-fluxo (step) como um objeto com o número da linha e os dados da linha. Se step não for configurado, o componente apenas lê o arquivo sem executar nada extra por linha.

5. Exemplos Práticos

Exemplo simples: um fluxo recebe uma planilha de clientes e usa o Excel Reader para ler a primeira aba a partir da segunda linha (pulando o cabeçalho), executando um sub-fluxo que cadastra cada cliente em um sistema.

Entrada (mensagem com o arquivo já anexado por um passo anterior, por exemplo um upload):

{
  "arquivoUpload": "<arquivo .xlsx binário, disponibilizado por um passo anterior>"
}

Configuração do componente:

{
  "componentName": "excel-reader",
  "configurations": {
    "fileName": "arquivoUpload",
    "firstRow": "2",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.exemplo.com/clientes", "method": "POST" }
    }
  }
}

Cada linha é entregue ao sub-fluxo assim (exemplo da linha 2 da planilha):

{
  "rowNumber": 2,
  "rowData": { "A": "Maria Silva", "B": "maria@exemplo.com", "C": "34" }
}

Resposta final (contadores, comportamento padrão de isAggregatedResult):

{
  "totalExecutedRows": 50,
  "success": 50,
  "error": 0
}

Exemplo avançado: o fluxo precisa ler uma aba específica chamada "Pedidos2026" de uma planilha com várias abas, e quer receber, ao final, o detalhe de cada linha processada (sucesso ou erro) para gerar um relatório de importação. Nesse caso, sheetName é preenchido com o nome exato da aba e isAggregatedResult é ativado.

Configuração do componente:

{
  "componentName": "excel-reader",
  "configurations": {
    "fileName": "arquivoUpload",
    "sheetName": "Pedidos2026",
    "firstRow": "2",
    "isAggregatedResult": "true",
    "step": {
      "componentName": "http",
      "configurations": { "url": "https://api.exemplo.com/pedidos", "method": "POST" }
    }
  }
}

Resposta final (detalhe de cada linha processada):

{
  "items": [
    { "body": "{\"status\":\"criado\",\"pedidoId\":101}" },
    { "body": "{\"error\":\"Campo 'valor' inválido na linha 3\"}" }
  ]
}

6. Como funciona a leitura

• Suporta o formato .xlsx (Excel moderno baseado em XML).
• Se sheetName não corresponder a nenhuma aba existente, nenhuma linha é lida (sem erro explícito).
• A leitura considera a primeira aba compatível encontrada por execução.
• Linhas totalmente vazias são ignoradas automaticamente.

7. Erros Comuns e Troubleshooting

Erro / Sintoma	Causa provável	Como resolver
"file name not found in configuration"	O campo fileName não foi preenchido.	Configurar fileName apontando para a propriedade correta da mensagem.
"file name [nome] not found in configuration"	O arquivo esperado não foi encontrado na mensagem com aquele nome.	Verificar se um passo anterior do fluxo realmente disponibilizou o arquivo com esse nome exato.
Nenhuma linha processada	sheetName não corresponde a nenhuma aba existente na planilha, ou o arquivo está vazio.	Conferir o nome exato da aba (sensível a maiúsculas/minúsculas é ignorado, mas precisa existir) e se a planilha tem dados.
Erro genérico ao abrir o arquivo	O arquivo enviado não é um .xlsx válido, ou está corrompido.	Confirmar que o arquivo é realmente um Excel .xlsx válido.