Pular para conteúdo

SFTP_EXISTS - Verificar Se Arquivo Existe no Servidor SFTP

O que é este Node?

O SFTP_EXISTS é o node responsável por verificar existência de arquivo/diretório em servidor SFTP. Retorna true/false sem listar conteúdo completo do diretório.

Por que este Node existe?

Validar existência antes de processar evita erros. O SFTP_EXISTS existe para:

  1. Validação Rápida: Verificar se arquivo esperado foi depositado
  2. Evitar Erros: Checar existência antes de download/delete
  3. Performance: Mais rápido que SFTP_LIST quando só precisa saber se existe
  4. Workflow Condicional: Tomar decisão baseada em existência

Como funciona internamente?

Quando o SFTP_EXISTS é executado, o sistema:

  1. Conecta via SSH: Túnel criptografado
  2. Executa Stat: Comando SFTP stat (obter atributos do arquivo)
  3. Verifica Resposta: Se retorna atributos = existe, se erro = não existe
  4. Retorna Boolean: true ou false
  5. Se falhar conexão: Erro de conexão
  6. Se arquivo não existe: Retorna exists: false
  7. Se arquivo existe: Retorna exists: true + metadados

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

private async fileExists(sftp: SFTP, remotePath: string): Promise<any> {
  try {
    const stats = await sftp.stat(remotePath);

    return {
      success: true,
      path: remotePath,
      exists: true,
      type: stats.isDirectory ? 'directory' : 'file',
      size: stats.size,
      modifiedAt: new Date(stats.mtime * 1000).toISOString(),
      protocol: 'sftp'
    };
  } catch (error) {
    // Arquivo não existe
    return {
      success: true,
      path: remotePath,
      exists: false,
      protocol: 'sftp'
    };
  }
}

Quando você DEVE usar este Node?

Use SFTP_EXISTS sempre que precisar de validar existência de arquivo:

Casos de uso

  1. Aguardar Arquivo: "Verificar se banco depositou arquivo de retorno antes de baixar"
  2. Validar Upload: "Confirmar que arquivo foi enviado com sucesso"
  3. Evitar Erros: "Checar se arquivo existe antes de tentar apagar"

Quando NÃO usar SFTP_EXISTS

  • Precisa Listar Todos: Use SFTP_LIST se precisa ver múltiplos arquivos
  • Já Sabe que Existe: Se tem certeza, faça download direto
  • FTP Básico: FTP padrão não tem comando exists (use FTP_LIST)

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
privateKey string Condicional Chave SSH
operation string Sim Deve ser "exists"
remotePath string Sim Arquivo/diretório a verificar
outputVariable string Não Variável resultado (padrão: sftp_result)

Exemplo 1: Aguardar Depósito de Arquivo Bancário

Objetivo: Verificar se banco depositou arquivo antes de processar

JSON para Importar

{
  "name": "Verificar Retorno Bancário",
  "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": "Arquivo Esperado",
        "parameters": {
          "variableName": "arquivo_retorno",
          "value": "/retornos/ret_2025-01-15.txt"
        }
      }
    },
    {
      "id": "sftp_exists",
      "type": "sftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Verificar Existência",
        "parameters": {
          "host": "sftp.banco.com.br",
          "username": "empresa",
          "password": "pass",
          "operation": "exists",
          "remotePath": "{{arquivo_retorno}}",
          "outputVariable": "check_arquivo"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Arquivo Existe?",
        "parameters": {
          "field": "{{check_arquivo.exists}}",
          "operator": "equals",
          "value": "true"
        }
      }
    },
    {
      "id": "message_yes",
      "type": "message",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "Encontrado",
        "parameters": {
          "message": "✅ Arquivo encontrado!\nTamanho: {{check_arquivo.size}} bytes\nPronto para processar."
        }
      }
    },
    {
      "id": "message_no",
      "type": "message",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "Não Encontrado",
        "parameters": {
          "message": "⏳ Arquivo ainda não foi depositado pelo banco.\nTente novamente mais tarde."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "sftp_exists" },
    { "source": "sftp_exists", "target": "condition_1" },
    { "source": "condition_1", "target": "message_yes", "label": "true" },
    { "source": "condition_1", "target": "message_no", "label": "false" },
    { "source": "message_yes", "target": "end_1" },
    { "source": "message_no", "target": "end_1" }
  ]
}

Saída esperada (se existe):

Sistema: ✅ Arquivo encontrado!
Tamanho: 204800 bytes
Pronto para processar.

Saída esperada (se não existe):

Sistema: ⏳ Arquivo ainda não foi depositado pelo banco.
Tente novamente mais tarde.

Exemplo 2: Validar Upload Bem-Sucedido

Objetivo: Confirmar que arquivo foi enviado com sucesso

JSON para Importar

{
  "name": "Upload e Validar",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "sftp_upload",
      "type": "sftp",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Upload Arquivo",
        "parameters": {
          "host": "sftp.server.com",
          "username": "user",
          "password": "pass",
          "operation": "upload",
          "localFilePath": "/tmp/documento.pdf",
          "remoteFilePath": "/uploads/documento.pdf"
        }
      }
    },
    {
      "id": "sftp_exists",
      "type": "sftp",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Verificar Upload",
        "parameters": {
          "host": "sftp.server.com",
          "username": "user",
          "password": "pass",
          "operation": "exists",
          "remotePath": "/uploads/documento.pdf",
          "outputVariable": "validacao"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "Upload confirmado: {{validacao.exists}}\nTamanho no servidor: {{validacao.size}} bytes"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "sftp_upload" },
    { "source": "sftp_upload", "target": "sftp_exists" },
    { "source": "sftp_exists", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Upload confirmado: true
Tamanho no servidor: 1048576 bytes

Resposta do Node

Se arquivo EXISTE:

{
  "success": true,
  "data": {
    "sftp_result": {
      "success": true,
      "path": "/retornos/ret_2025-01-15.txt",
      "exists": true,
      "type": "file",
      "size": 204800,
      "modifiedAt": "2025-01-15T08:00:00.000Z",
      "protocol": "sftp"
    }
  }
}

Se arquivo NÃO EXISTE:

{
  "success": true,
  "data": {
    "sftp_result": {
      "success": true,
      "path": "/retornos/ret_2025-01-15.txt",
      "exists": false,
      "protocol": "sftp"
    }
  }
}

Boas Práticas

✅ SIM:

  • Use SFTP_EXISTS antes de download/delete
  • Combine com CONDITION para fluxo condicional
  • Verifique exists: true antes de processar
  • Use para aguardar arquivo em polling

❌ NÃO:

  • Não assuma que arquivo sempre existirá
  • Não ignore resultado exists: false
  • Não use para listar múltiplos arquivos (use SFTP_LIST)

Dicas

💡 Dica 1: SFTP_EXISTS é mais rápido que SFTP_LIST quando só precisa saber se 1 arquivo existe.

💡 Dica 2: Combine com DELAY + LOOP para aguardar depósito: verificar a cada 5 minutos até exists: true.

💡 Dica 3: Retorna metadados se existe (size, modifiedAt, type). Use para decisões.

💡 Dica 4: Se exists: false, não significa erro. Arquivo simplesmente não existe (ainda).

Próximos Nodes

→ SFTP_DOWNLOAD - Baixar após confirmar existência → SFTP_LIST - Listar múltiplos arquivos → CONDITION - Decidir baseado em exists → DELAY - Aguardar antes de verificar novamente