SFTP_LIST - Listar Arquivos no Servidor SFTP

O que é este Node?

O SFTP_LIST é o node responsável por listar arquivos e diretórios em servidor SFTP via SSH. Equivalente ao FTP_LIST, mas com conexão criptografada.

Por que este Node existe?

Visualizar conteúdo remoto de forma segura é essencial. O SFTP_LIST existe para:

1. Descoberta Segura: Listar arquivos via canal SSH criptografado
2. Auditoria: Logs SSH registram quem listou o quê e quando
3. Metadados Completos: SSH fornece permissões, proprietário, grupo detalhadamente
4. Preparação: Verificar arquivos antes de baixar/processar

Como funciona internamente?

Quando o SFTP_LIST é executado, o sistema:

1. Conecta via SSH: Túnel criptografado na porta 22
2. Navega para Diretório: Acessa path especificado
3. Lista via SFTP: Executa comando SFTP list
4. Processa Atributos: Extrai nome, tipo, tamanho, permissões, datas
5. Retorna Array: Lista completa de arquivos e diretórios
6. Se falhar: Erro (sem permissão, path não existe)
7. Se sucesso: Array com metadados completos

Código interno (sftp-executor.service.ts - não implementado ainda):

private async listFiles(sftp: SFTP, remotePath: string): Promise<any> {
  const path = remotePath || '/';
  const files = await sftp.list(path);

  return {
    success: true,
    path,
    files: files.map(file => ({
      name: file.name,
      type: file.type === 'd' ? 'directory' : 'file',
      size: file.size,
      modifiedAt: new Date(file.modifyTime).toISOString(),
      permissions: file.rights,
      owner: file.owner,
      group: file.group
    })),
    count: files.length,
    protocol: 'sftp'
  };
}

Quando você DEVE usar este Node?

Use SFTP_LIST sempre que precisar de listar arquivos em servidor SSH:

Casos de uso

1. Verificar Disponibilidade: "Listar /incoming/ para ver se banco depositou arquivo de retorno"
2. Processar Lote: "Listar XMLs de NF-e para processar um por um"
3. Auditoria: "Verificar permissões e proprietários de arquivos sensíveis"

Quando NÃO usar SFTP_LIST

• Arquivo Específico: Use SFTP_EXISTS se sabe nome exato
• Servidor FTP: Use FTP_LIST se servidor não tem SSH

Parâmetros

Campo	Tipo	Obrigatório	Descrição
host	string	Sim	Servidor SFTP
port	number	Não	Porta SSH (padrão: 22)
username	string	Sim	Usuário SSH
password	string	Condicional	Senha (ou privateKey)
privateKey	string	Condicional	Chave SSH
operation	string	Sim	Deve ser "list"
remotePath	string	Não	Diretório (padrão: /)
outputVariable	string	Não	Variável resultado

Exemplo 1: Listar Arquivos Bancários Disponíveis

Objetivo: Verificar arquivos de retorno depositados pelo banco

JSON para Importar

{
  "name": "Listar SFTP Retornos Bancários",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sftp_1",
      "type": "sftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Listar Retornos",
        "parameters": {
          "host": "sftp.banco.com.br",
          "port": 22,
          "username": "empresa",
          "password": "pass",
          "operation": "list",
          "remotePath": "/retornos/",
          "outputVariable": "lista_retornos"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Resultado",
        "parameters": {
          "message": "📋 Arquivos disponíveis: {{lista_retornos.count}}\nPasta: {{lista_retornos.path}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sftp_1" },
    { "source": "sftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 📋 Arquivos disponíveis: 7
Pasta: /retornos/

Resposta do Node

{
  "success": true,
  "data": {
    "sftp_result": {
      "success": true,
      "path": "/retornos/",
      "count": 2,
      "protocol": "sftp",
      "files": [
        {
          "name": "retorno_2025-01-15.ret",
          "type": "file",
          "size": 102400,
          "modifiedAt": "2025-01-15T08:00:00.000Z",
          "permissions": "rw-r--r--",
          "owner": "banco",
          "group": "clientes"
        },
        {
          "name": "cobranca.txt",
          "type": "file",
          "size": 51200,
          "modifiedAt": "2025-01-15T09:30:00.000Z",
          "permissions": "rw-r--r--",
          "owner": "banco",
          "group": "clientes"
        }
      ]
    }
  }
}

Boas Práticas

✅ SIM:

• Use SFTP_LIST antes de baixar múltiplos arquivos
• Filtre por extensão ou padrão de nome
• Combine com LOOP para processar cada arquivo

❌ NÃO:

• Não assuma que pasta sempre terá arquivos
• Não liste diretórios gigantes sem necessidade

Dicas

💡 Dica 1: Array files contém: name, type, size, modifiedAt, permissions, owner, group.

💡 Dica 2: Use CONDITION para filtrar: {{lista.files}} contains ".xml"

💡 Dica 3: Para processar todos: SFTP_LIST + LOOP + SFTP_DOWNLOAD.

Próximos Nodes

→ SFTP_DOWNLOAD - Baixar da lista → SFTP_DELETE - Apagar da lista → LOOP - Iterar sobre array