Pular para conteúdo

FTP_CONNECT - Conectar ao Servidor FTP

O que é este Node?

O FTP_CONNECT é o node responsável por estabelecer conexão com servidores FTP/FTPS remotos. Este é o ponto de entrada para todas as operações de transferência de arquivos via protocolo FTP.

Por que este Node existe?

Servidores FTP são amplamente usados para transferência de arquivos entre sistemas. O FTP_CONNECT existe para:

  1. Gerenciar Transferências de Arquivos: Conectar a servidores para upload/download de documentos, imagens e dados
  2. Integrar com Sistemas Legados: Muitos sistemas ainda usam FTP como método principal de troca de dados
  3. Automatizar Backups: Fazer backup automático de arquivos para servidores remotos
  4. Sincronizar Dados: Manter arquivos sincronizados entre diferentes sistemas

Como funciona internamente?

Quando o FTP_CONNECT é executado, o sistema:

  1. Valida Credenciais: Verifica se host, username e password foram fornecidos
  2. Determina Porta: Usa porta 21 (padrão FTP) ou porta customizada
  3. Configura Segurança: Define se usa FTP padrão ou FTPS (FTP com SSL/TLS)
  4. Estabelece Conexão: Cria conexão TCP com o servidor remoto
  5. Autentica: Envia credenciais e aguarda confirmação
  6. Se falhar: Retorna erro com detalhes da falha de conexão
  7. Se sucesso: Mantém conexão aberta para operações subsequentes

Código interno (ftp-executor.service.ts:268-282): 

private async connectFTP(client: FTP.Client, data: FTPNodeData): Promise<void> {
  const config: FTPConnectionConfig = {
    host: data.host!,
    port: data.port || 21,
    user: data.username!,
    password: data.password!,
    secure: data.secure || false
  };

  this.logger.debug(`Connecting to FTP server: ${config.host}:${config.port}`);

  await client.access(config);

  this.logger.debug('FTP connection established');
}

Quando você DEVE usar este Node?

Use FTP_CONNECT sempre que precisar de transferir arquivos via protocolo FTP:

Casos de uso

  1. Upload de Relatórios: "Enviar relatórios diários gerados pelo sistema para servidor FTP do cliente"
  2. Download de Arquivos CSV: "Baixar arquivos CSV de pedidos do servidor FTP do fornecedor para processar"
  3. Backup Automatizado: "Fazer backup de documentos importantes para servidor FTP externo todas as noites"

Quando NÃO usar FTP_CONNECT

  • Transferências Modernas: Use SFTP_CONNECT (mais seguro) ou APIs REST quando disponíveis
  • Armazenamento Cloud: Use S3, Google Drive ou Dropbox nodes para cloud storage
  • Arquivos Pequenos: Para enviar arquivos via WhatsApp, use node MEDIA diretamente

Parâmetros Detalhados

host (string, obrigatório)

O que é: Endereço do servidor FTP (domínio ou IP).

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste FTP Connect - Host",
  "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": "Conectar FTP",
        "parameters": {
          "host": "ftp.example.com",
          "username": "user",
          "password": "pass123",
          "operation": "list",
          "remotePath": "/",
          "outputVariable": "ftp_connection"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar Conexão",
        "parameters": {
          "message": "Conectado ao servidor: {{ftp_connection.host}}"
        }
      }
    },
    {
      "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: Inicie o flow. Sistema deve mostrar "Conectado ao servidor: ftp.example.com"

port (number, opcional)

O que é: Porta TCP do servidor FTP.

Padrão: 21 (porta padrão FTP)

Flow completo para testar:

{
  "name": "Teste FTP Connect - Porta Customizada",
  "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": "Conectar FTP Porta 2121",
        "parameters": {
          "host": "ftp.custom.com",
          "port": 2121,
          "username": "admin",
          "password": "secret",
          "operation": "list",
          "remotePath": "/",
          "outputVariable": "ftp_result"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Conectado na porta customizada!"
        }
      }
    },
    {
      "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: Se o servidor usar porta não-padrão (como 2121 ou 2222), especifique aqui.

username (string, obrigatório)

O que é: Nome de usuário para autenticação no servidor FTP.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste FTP Connect - Username",
  "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 Username",
        "parameters": {
          "message": "Digite o username do FTP:",
          "variableName": "ftp_user"
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Conectar com Username Dinâmico",
        "parameters": {
          "host": "ftp.example.com",
          "username": "{{ftp_user}}",
          "password": "pass123",
          "operation": "list",
          "remotePath": "/"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Autenticado como: {{ftp_user}}"
        }
      }
    },
    {
      "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 um username válido. Sistema deve autenticar com sucesso.

password (string, obrigatório)

O que é: Senha para autenticação no servidor FTP.

Padrão: Nenhum (obrigatório)

Flow completo para testar:

{
  "name": "Teste FTP Connect - Password",
  "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 Senha Segura",
        "parameters": {
          "variableName": "ftp_password",
          "value": "MySecureP@ssw0rd!"
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Conectar com Senha",
        "parameters": {
          "host": "ftp.example.com",
          "username": "admin",
          "password": "{{ftp_password}}",
          "operation": "list",
          "remotePath": "/"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Sucesso",
        "parameters": {
          "message": "Autenticado com segurança!"
        }
      }
    },
    {
      "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: Senha será usada de forma segura através de variável. Nunca hardcode senhas no flow!

secure (boolean, opcional)

O que é: Ativa FTPS (FTP com SSL/TLS) para conexão criptografada.

Padrão: false (FTP sem criptografia)

Flow completo para testar:

{
  "name": "Teste FTP Connect - FTPS Seguro",
  "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": "Conectar FTPS Seguro",
        "parameters": {
          "host": "ftps.example.com",
          "port": 990,
          "username": "secure_user",
          "password": "secure_pass",
          "secure": true,
          "operation": "list",
          "remotePath": "/"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar Segurança",
        "parameters": {
          "message": "Conexão FTPS estabelecida com criptografia SSL/TLS!"
        }
      }
    },
    {
      "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: Use secure: true para servidores FTPS. Porta padrão FTPS é 990.

Parâmetros

Campo Tipo Obrigatório Descrição
host string Sim Endereço do servidor FTP (domínio ou IP)
port number Não Porta TCP (padrão: 21)
username string Sim Nome de usuário para autenticação
password string Sim Senha para autenticação
secure boolean Não Ativar FTPS - SSL/TLS (padrão: false)
operation string Sim Operação: list (para testar conexão)
remotePath string Não Caminho remoto (padrão: /)
outputVariable string Não Variável para armazenar resultado (padrão: ftp_result)

Exemplo 1: Conexão FTP Simples para Listar Arquivos

Objetivo: Conectar a servidor FTP e listar arquivos do diretório raiz

JSON para Importar

{
  "name": "Conexão FTP Simples",
  "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": "Conectar ao FTP",
        "parameters": {
          "host": "ftp.dlptest.com",
          "port": 21,
          "username": "dlpuser",
          "password": "rNrKYTX9g7z3RgJRmxWuGHbeu",
          "secure": false,
          "operation": "list",
          "remotePath": "/",
          "outputVariable": "file_list"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Mostrar Resultado",
        "parameters": {
          "message": "Encontrados {{file_list.count}} arquivos no servidor!"
        }
      }
    },
    {
      "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" }
  ]
}

Saída esperada:

Sistema: Encontrados 5 arquivos no servidor!

Exemplo 2: Conexão FTPS Segura com Credenciais Dinâmicas

Objetivo: Pedir credenciais ao usuário e conectar via FTPS seguro

JSON para Importar

{
  "name": "FTPS com Credenciais Dinâmicas",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 100, "y": 200 },
      "data": {
        "label": "Pedir Host",
        "parameters": {
          "message": "Digite o endereço do servidor FTP:",
          "variableName": "server_host"
        }
      }
    },
    {
      "id": "input_2",
      "type": "input",
      "position": { "x": 100, "y": 300 },
      "data": {
        "label": "Pedir Username",
        "parameters": {
          "message": "Digite seu username:",
          "variableName": "server_user"
        }
      }
    },
    {
      "id": "input_3",
      "type": "input",
      "position": { "x": 100, "y": 400 },
      "data": {
        "label": "Pedir Senha",
        "parameters": {
          "message": "Digite sua senha:",
          "variableName": "server_pass"
        }
      }
    },
    {
      "id": "ftp_1",
      "type": "ftp",
      "position": { "x": 300, "y": 300 },
      "data": {
        "label": "Conectar FTPS",
        "parameters": {
          "host": "{{server_host}}",
          "port": 990,
          "username": "{{server_user}}",
          "password": "{{server_pass}}",
          "secure": true,
          "operation": "list",
          "remotePath": "/",
          "outputVariable": "connection_result"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 300 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "✅ Conectado com segurança ao {{server_host}}!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 300 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "input_2" },
    { "source": "input_2", "target": "input_3" },
    { "source": "input_3", "target": "ftp_1" },
    { "source": "ftp_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Digite o endereço do servidor FTP:
Usuário: ftps.example.com
Sistema: Digite seu username:
Usuário: admin
Sistema: Digite sua senha:
Usuário: ********
Sistema: ✅ Conectado com segurança ao ftps.example.com!

Resposta do Node

{
  "success": true,
  "data": {
    "ftp_result": {
      "success": true,
      "path": "/",
      "files": [],
      "count": 0
    },
    "operation": "list",
    "host": "ftp.example.com",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "executionTime": 1234
}

Boas Práticas

✅ SIM:

  • Use secure: true sempre que possível para criptografar conexões
  • Armazene credenciais em variáveis, nunca hardcode no flow
  • Teste conexão com operação list antes de outras operações
  • Use porta 990 para FTPS e 21 para FTP padrão
  • Valide se servidor está acessível antes de processar múltiplos arquivos

❌ NÃO:

  • Não exponha senhas em logs ou mensagens
  • Não use FTP sem criptografia para dados sensíveis
  • Não hardcode credenciais diretamente nos parâmetros
  • Não assuma que porta 21 sempre funcionará (alguns usam portas customizadas)

Dicas

💡 Dica 1: FTP padrão (porta 21) não criptografa dados. Use FTPS (porta 990, secure:true) ou SFTP para segurança.

💡 Dica 2: Servidores FTP públicos para teste: ftp.dlptest.com (user: dlpuser, pass: rNrKYTX9g7z3RgJRmxWuGHbeu)

💡 Dica 3: Se conexão falhar, verifique firewall (porta TCP deve estar aberta) e credenciais.

💡 Dica 4: FTPS (FTP + SSL) ≠ SFTP (SSH File Transfer Protocol). São protocolos diferentes! Use SFTP_CONNECT para SFTP.

Próximos Nodes

→ FTP_UPLOAD - Enviar arquivo para servidor FTP → FTP_DOWNLOAD - Baixar arquivo do servidor FTP → FTP_LIST - Listar arquivos no servidor FTP → SFTP_CONNECT - Conectar via SFTP (mais seguro)