Pular para conteúdo

FTP_DOWNLOAD - Baixar Arquivo do Servidor FTP

O que é este Node?

O FTP_DOWNLOAD é o node responsável por baixar arquivos de um servidor FTP remoto para o sistema local. Permite recuperar arquivos armazenados em servidores FTP externos.

Por que este Node existe?

Buscar arquivos de servidores remotos é essencial para integrações e automações. O FTP_DOWNLOAD existe para:

  1. Processar Arquivos de Parceiros: Baixar pedidos, notas fiscais e documentos enviados por fornecedores via FTP
  2. Sincronizar Dados: Buscar arquivos atualizados de sistemas externos para processar localmente
  3. Recuperar Backups: Baixar backups armazenados em servidores FTP para restauração
  4. Integração B2B: Receber arquivos de parceiros que disponibilizam via FTP

Como funciona internamente?

Quando o FTP_DOWNLOAD é executado, o sistema:

  1. Conecta ao FTP: Estabelece conexão com servidor usando credenciais fornecidas
  2. Valida Arquivo Remoto: Verifica existência do arquivo no caminho remoto especificado
  3. Cria Diretório Local: Se necessário, cria diretórios locais para salvar o arquivo
  4. Baixa Arquivo: Transfere bytes do servidor remoto para arquivo local
  5. Registra Tamanho: Captura tamanho do arquivo baixado para confirmação
  6. Se falhar: Retorna erro detalhando problema (arquivo não encontrado, sem permissão, etc)
  7. Se sucesso: Confirma download com timestamp e detalhes do arquivo

Código interno (ftp-executor.service.ts:306-327): 

private async downloadFile(client: FTP.Client, data: FTPNodeData): Promise<any> {
  const remotePath = data.remoteFilePathDownload!;
  const localPath = data.localFilePathDownload!;

  // Ensure local directory exists
  const localDir = path.dirname(localPath);
  if (!fs.existsSync(localDir)) {
    fs.mkdirSync(localDir, { recursive: true });
  }

  this.logger.debug(`Downloading file: ${remotePath} → ${localPath}`);

  await client.downloadTo(localPath, remotePath);

  return {
    success: true,
    remotePath,
    localPath,
    size: fs.statSync(localPath).size,
    downloadedAt: new Date().toISOString()
  };
}

Quando você DEVE usar este Node?

Use FTP_DOWNLOAD sempre que precisar de buscar arquivos de servidor FTP remoto:

Casos de uso

  1. Processar Pedidos: "Baixar arquivo CSV de pedidos do servidor FTP do fornecedor todas as manhãs às 8h"
  2. Importar Dados: "Baixar planilha Excel atualizada do servidor do cliente para importar produtos"
  3. Recuperar Documentos: "Baixar notas fiscais XML disponibilizadas pelo contador via FTP"

Quando NÃO usar FTP_DOWNLOAD

  • APIs Disponíveis: Use endpoints REST se a aplicação oferecer API moderna
  • Cloud Storage: Use nodes S3, Google Drive ou Dropbox para buscar de cloud
  • Transferências Seguras: Use SFTP_DOWNLOAD para dados sensíveis (mais seguro)

Parâmetros Detalhados

remoteFilePathDownload (string, obrigatório)

O que é: Caminho completo do arquivo no servidor FTP remoto que será baixado.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste FTP Download - RemotePath",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Definir Arquivo Remoto",
        "parameters": {
          "variableName": "remote_file",
          "value": "/exports/pedidos_2025-01-15.csv"
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Download Arquivo",
        "parameters": {
          "host": "ftp.fornecedor.com",
          "username": "empresa",
          "password": "pass123",
          "operation": "download",
          "remoteFilePathDownload": "{{remote_file}}",
          "localFilePathDownload": "/tmp/pedidos.csv",
          "outputVariable": "download_result"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Arquivo baixado: {{download_result.size}} bytes"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O arquivo deve existir no servidor remoto no caminho especificado.

localFilePathDownload (string, obrigatório)

O que é: Caminho completo onde o arquivo será salvo no sistema local.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste FTP Download - LocalPath",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Pedir Caminho Local",
        "parameters": {
          "message": "Onde salvar? (Ex: /tmp/arquivo.pdf)",
          "variableName": "local_path"
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Download com Path Dinâmico",
        "parameters": {
          "host": "ftp.servidor.com",
          "username": "user",
          "password": "pass",
          "operation": "download",
          "remoteFilePathDownload": "/docs/manual.pdf",
          "localFilePathDownload": "{{local_path}}"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Arquivo salvo em: {{local_path}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Digite "/tmp/manual.pdf". Sistema baixará e salvará neste caminho.

outputVariable (string, opcional)

O que é: Nome da variável onde resultado do download será armazenado.

Padrão: "ftp_result"

Flow completo para testar:

{
  "name": "Teste FTP Download - OutputVariable",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Download com Variável Customizada",
        "parameters": {
          "host": "ftp.backup.com",
          "username": "backup",
          "password": "pass",
          "operation": "download",
          "remoteFilePathDownload": "/backups/database.sql",
          "localFilePathDownload": "/tmp/restore.sql",
          "outputVariable": "download_info"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Detalhes",
        "parameters": {
          "message": "Download concluído!\nArquivo: {{download_info.localPath}}\nTamanho: {{download_info.size}} bytes\nHora: {{download_info.downloadedAt}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: Resultado fica disponível em {{download_info}} para usar em nodes posteriores.

Parâmetros

Campo Tipo Obrigatório Descrição
host string Sim Endereço do servidor FTP
port number Não Porta TCP (padrão: 21)
username string Sim Nome de usuário
password string Sim Senha
secure boolean Não FTPS - SSL/TLS (padrão: false)
operation string Sim Deve ser "download"
remoteFilePathDownload string Sim Caminho do arquivo no servidor remoto
localFilePathDownload string Sim Caminho onde salvar localmente
outputVariable string Não Variável de resultado (padrão: ftp_result)

Exemplo 1: Download Diário de Arquivo CSV de Pedidos

Objetivo: Baixar automaticamente arquivo de pedidos todas as manhãs às 8h

JSON para Importar

{
  "name": "Download Automático Pedidos",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início (8h diariamente)" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Data de Hoje",
        "parameters": {
          "variableName": "hoje",
          "value": "2025-01-15"
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Baixar Pedidos",
        "parameters": {
          "host": "ftp.fornecedor.com",
          "port": 21,
          "username": "empresa_pedidos",
          "password": "secret123",
          "secure": false,
          "operation": "download",
          "remoteFilePathDownload": "/exports/pedidos_{{hoje}}.csv",
          "localFilePathDownload": "/var/imports/pedidos_{{hoje}}.csv",
          "outputVariable": "pedidos_info"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Notificar",
        "parameters": {
          "message": "✅ Pedidos baixados!\nArquivo: pedidos_{{hoje}}.csv\nTamanho: {{pedidos_info.size}} bytes\nPronto para processar!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: ✅ Pedidos baixados!
Arquivo: pedidos_2025-01-15.csv
Tamanho: 1048576 bytes
Pronto para processar!

Exemplo 2: Download com Verificação de Múltiplos Arquivos

Objetivo: Baixar vários arquivos do servidor FTP e confirmar cada um

JSON para Importar

{
  "name": "Download Múltiplos Arquivos",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Baixar Arquivo 1",
        "parameters": {
          "host": "ftp.docs.com",
          "username": "download_user",
          "password": "pass123",
          "operation": "download",
          "remoteFilePathDownload": "/invoices/nf_001.xml",
          "localFilePathDownload": "/tmp/nf_001.xml",
          "outputVariable": "nf1"
        }
      }
    },
    {
      "id": "ftp_2",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Baixar Arquivo 2",
        "parameters": {
          "host": "ftp.docs.com",
          "username": "download_user",
          "password": "pass123",
          "operation": "download",
          "remoteFilePathDownload": "/invoices/nf_002.xml",
          "localFilePathDownload": "/tmp/nf_002.xml",
          "outputVariable": "nf2"
        }
      }
    },
    {
      "id": "ftp_3",
      "type": "ftp",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Baixar Arquivo 3",
        "parameters": {
          "host": "ftp.docs.com",
          "username": "download_user",
          "password": "pass123",
          "operation": "download",
          "remoteFilePathDownload": "/invoices/nf_003.xml",
          "localFilePathDownload": "/tmp/nf_003.xml",
          "outputVariable": "nf3"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Resumo",
        "parameters": {
          "message": "📥 3 notas fiscais baixadas:\n✅ {{nf1.localPath}}\n✅ {{nf2.localPath}}\n✅ {{nf3.localPath}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "ftp_2" },
    { "source": "ftp_2", "target": "ftp_3" },
    { "source": "ftp_3", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 📥 3 notas fiscais baixadas:
✅ /tmp/nf_001.xml
✅ /tmp/nf_002.xml
✅ /tmp/nf_003.xml

Exemplo 3: Download Seguro com FTPS

Objetivo: Baixar backup de forma segura usando FTPS (FTP com SSL/TLS)

JSON para Importar

{
  "name": "Download Seguro Backup",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Iniciar Download",
        "parameters": {
          "message": "🔄 Iniciando download seguro do backup..."
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Download FTPS Seguro",
        "parameters": {
          "host": "ftps.backup.com",
          "port": 990,
          "username": "backup_admin",
          "password": "SuperSecure@123",
          "secure": true,
          "operation": "download",
          "remoteFilePathDownload": "/backups/database_2025-01-15.sql.gz",
          "localFilePathDownload": "/var/backups/database_restore.sql.gz",
          "outputVariable": "backup_info"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar Sucesso",
        "parameters": {
          "message": "✅ Backup baixado com segurança!\nArquivo: {{backup_info.localPath}}\nTamanho: {{backup_info.size}} bytes\nCriptografia: SSL/TLS ativa"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "message_1" },
    { "source": "message_1", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_2" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: 🔄 Iniciando download seguro do backup...
Sistema: ✅ Backup baixado com segurança!
Arquivo: /var/backups/database_restore.sql.gz
Tamanho: 52428800 bytes
Criptografia: SSL/TLS ativa

Resposta do Node

{
  "success": true,
  "data": {
    "ftp_result": {
      "success": true,
      "remotePath": "/exports/pedidos.csv",
      "localPath": "/tmp/pedidos.csv",
      "size": 1048576,
      "downloadedAt": "2025-01-15T08:00:00.000Z"
    },
    "operation": "download",
    "host": "ftp.fornecedor.com",
    "timestamp": "2025-01-15T08:00:00.000Z"
  },
  "executionTime": 3456,
  "logs": [
    "Downloaded file: /exports/pedidos.csv → /tmp/pedidos.csv"
  ]
}

Boas Práticas

✅ SIM:

  • Crie diretórios locais antes do download (o sistema faz automaticamente)
  • Use caminhos absolutos para evitar problemas de localização
  • Baixe para /tmp/ se arquivo for temporário, use /var/ para permanentes
  • Configure timeout adequado para arquivos grandes
  • Use FTPS (secure: true) para download de dados sensíveis

❌ NÃO:

  • Não tente baixar arquivos que não existem no servidor
  • Não sobrescreva arquivos importantes sem fazer backup primeiro
  • Não assuma que download sempre será rápido (depende do tamanho)
  • Não ignore erros de download - sempre trate falhas
  • Não baixe para diretórios sem permissão de escrita

Dicas

💡 Dica 1: Velocidade do download depende da sua conexão. Arquivo de 100MB pode levar minutos.

💡 Dica 2: Se download falhar, verifique: (1) arquivo existe no servidor, (2) você tem permissão de leitura, (3) espaço em disco local disponível.

💡 Dica 3: Para baixar múltiplos arquivos, use FTP_LIST primeiro para obter lista, depois LOOP para baixar cada um.

💡 Dica 4: Diretórios locais são criados automaticamente se não existirem. Ex: /var/imports/2025/01/ será criado se necessário.

Próximos Nodes

→ FTP_UPLOAD - Enviar arquivo para servidor FTP → FTP_LIST - Listar arquivos disponíveis antes de baixar → FTP_DELETE - Apagar arquivo remoto após baixar → SFTP_DOWNLOAD - Baixar via SFTP (mais seguro)