SFTP

25 min

Objetivo

O conector SFTP (Secure File Transfer Protocol) permite a transferência segura de arquivos entre sistemas e servidores remotos. Com ele, é possível realizar operações como upload (envio) e download (recebimento) de arquivos através de uma conexão criptografada, assegurando a proteção dos dados durante a transferência.

Criando uma conexão

Antes de usar o conector SFTP, é necessária a criação de uma conexão. Vamos lá.

Clique em Propriedades.

Em Selecionar uma conexão clique em Criar nova conexão.

Vamos preencher os dados da conexão.

Com dados de sua conexão preenchidos, clique em Salvar conexão.

Agora você já pode montar seus fluxos utilizando o Conector SFTP.

Utilizando o Conector SFTP

Com uma Conexão SFTP configurada, vamos criar um novo fluxo, quer irá criar um arquivo JSON, em SFTP a partir de uma requisição HTTP

Selecionamos o modo canvas, e com editor canvas aberto, vamos arrastar dois conectores, sendo um HTTP e outro SFTP, na sequência faremos a linkage como à imagem abaixo.

Vamos a configuração do primeiro passo:

1 ) - Clique no connector para configurar

2 ) - Aba parametrização, no caso especifico usaremos o método GET, também utilizaremos uma URL random, que nos gera dados aleatórios.

3 ) - Aba propriedades, vamos informar apenas o nome do passo, já que não temos autenticação à fazer.

Configurando segundo passo com SFTP

1 ) - Clique no connector para configurar

3 ) - Aba parametrização

4 ) - Selecionamos a operação desejada, no caso vamos criar um arquivo para salvar o payload da requisição HTTP.

5 ) - Caminho do arquivo: aqui é o caminho relativo onde queremos salvar (pode ser "/" ou qualquer outro, desde que exista no servidor e o usuário tenha permissão de escrita).

6 ) - Nome do arquivo: aqui informaremos o nome que pode ser fixo, ou como no caso, usaremos o resultado da requisição HTTP, para criar um arquivo com nome dinâmico, baseado no valor de um campo "uid", esse campo nos retorna um UUID, OBS: é necessário o uso da função "get' para mais detalhes, visite o Link

7 ) - Conteúdo do aquivo: aqui também temos as mesmas possibilidades do campo nome, e mais a de salvar todo o payload da requisição HTTP, ou de qualquer outro passo anterior, no campo nosso retorno é um JSON, e precisaremos usar uma função "getJsonEscaped" que irá retornar JSON qus erá salvo j no arquivo.

Obs: Esse campo também suporta conteudos de arquivos em base64, ele fará o decode do mesmo e criar o arquivo no diretório informado.

8 ) - Aba propriedades, vamos informar o nome do passo e a conexão que será utilizada

9 ) - Executaremos um teste de todos fluxo.

10 ) - Com teste finalizado, podemos analisar os detalhes

Nesse caso, nossa requisição HTTP nos retornou o payload a seguir

Saída HTTP

{
    "id": 53,
    "uid": "d774bc23-9b40-406f-9d38-4fd40ca66b70", // campo que usamos para nomear o arquivo
    "password": "wecZtfC46B",
    "first_name": "Kevin",
    "last_name": "Lynch",
    "username": "kevin.lynch",
    "email": "[email protected]",
    "avatar": "https://robohash.org/fugitveritatisrerum.png?size=300x300\u0026set=set1",
    "gender": "Polygender",
    "phone_number": "+251 1-204-707-6787",
    "social_insurance_number": "948033170",
    "date_of_birth": "2004-03-13",
    "employment": {
        "title": "Retail Facilitator",
        "key_skill": "Communication"
    },
    "address": {
        "city": "Samton",
        "street_name": "Okuneva Meadows",
        "street_address": "5699 Bechtelar Divide",
        "zip_code": "37772-5477",
        "state": "Colorado",
        "country": "United States",
        "coordinates": {
            "lat": 72.71042078010802,
            "lng": 69.74851376761379
        }
    },
    "credit_card": {
        "cc_number": "4233-8980-1719-5205"
    },
    "subscription": {
        "plan": "Starter",
        "status": "Blocked",
        "payment_method": "Bitcoins",
        "term": "Full subscription"
    }
}

Entrada SFTP

{
    "operation": "create",
    "file_content": "{\"address\":{\"city\":\"Samton\",\"coordinates\":{\"lat\":72.71042078010802,\"lng\":69.74851376761379},\"country\":\"United States\",\"state\":\"Colorado\",\"street_address\":\"5699 Bechtelar Divide\",\"street_name\":\"Okuneva Meadows\",\"zip_code\":\"37772-5477\"},\"avatar\":\"https://robohash.org/fugitveritatisrerum.png?size=300x300\\u0026set=set1\",\"credit_card\":{\"cc_number\":\"4233-8980-1719-5205\"},\"date_of_birth\":\"2004-03-13\",\"email\":\"[email protected]\",\"employment\":{\"key_skill\":\"Communication\",\"title\":\"Retail Facilitator\"},\"first_name\":\"Kevin\",\"gender\":\"Polygender\",\"id\":53,\"last_name\":\"Lynch\",\"password\":\"wecZtfC46B\",\"phone_number\":\"+251 1-204-707-6787\",\"social_insurance_number\":\"948033170\",\"subscription\":{\"payment_method\":\"Bitcoins\",\"plan\":\"Starter\",\"status\":\"Blocked\",\"term\":\"Full subscription\"},\"uid\":\"d774bc23-9b40-406f-9d38-4fd40ca66b70\",\"username\":\"kevin.lynch\"}",
    "file_name": "d774bc23-9b40-406f-9d38-4fd40ca66b70.json", // Veja como ficou o nome do arquivo
    "file_path": "/upload"
}

Saída SFTP (Esse retorno muda de acordo com a operação)

SUCCESS

bas

Operação CreateFileFromTemp - SFTP

Descrição

A operação Criar um arquivo da pasta temporária do conector SFTP permite enviar arquivos para um servidor SFTP a partir de arquivos armazenados na pasta temporária do sistema. Esta operação é especialmente útil quando você precisa processar um arquivo em etapas anteriores do fluxo (é comumente utilizada em conjunto com outros conectores, como o conector CSV que mantém o arquivo na pasta temporária durante a execução do fluxo) e depois enviá-lo via SFTP.

Como Funciona

Leitura do arquivo temporário: O conector lê o arquivo da pasta temporária

Carregamento do conteúdo: O conteúdo do arquivo é carregado na memória

Envio via SFTP: O arquivo é enviado para o servidor SFTP no caminho especificado

Parâmetros de Entrada

A operação Criar um arquivo da pasta temporária requer os seguintes parâmetros:

Campos Obrigatórios

Campo	Tipo	Descrição
Nome do arquivo de saída	string	Nome do arquivo na pasta temporária que será enviado
Caminho do diretório	string	Caminho de destino no servidor SFTP onde o arquivo será salvo
config.new_file_path	string	Novo caminho para mover arquivo após envio

Exemplo de JSON de Saída

Resposta de Sucesso

{
  "message": "Arquivo CSV relatorio_vendas.csv enviado com sucesso via SFTP."
}

Resposta de Erro - Arquivo não encontrado

{
  "code": "sftp-csv-read-error",
  "message": "erro ao ler arquivo CSV temporário relatorio_vendas.csv: no such file or directory"
}

Resposta de Erro - Falha no envio SFTP

{
  "code": "sftp-send-csv-error",
  "message": "failed to upload file: permission denied"
}

Resposta de Erro - Conexão SFTP

{
  "code": "sftp-connection-error",
  "message": "failed to connect to SFTP server: dial tcp 192.168.1.200:22: connection refused"
}

Operação Mover Arquivo

A operação Move Arquivo permite mover arquivos em um servidor SFTP ou entre conexões SFTP diferentes. Essa funcionalidade é útil para organizar, renomear ou transferir arquivos entre diretórios e servidores de forma segura e automatizada.

Como Funciona

Durante a execução, o sistema tentará mover o arquivo especificado para o destino desejado. A operação pode manter o mesmo nome do arquivo ou renomeá-lo durante o processo.

Caso o destino já contenha um arquivo com o mesmo nome, é possível habilitar a sobrescrita. Se ocorrer algum erro, o sistema realiza um rollback automático, tentando restaurar o arquivo original.

⚠️ Atenção: Caso a restauração também falhe, o arquivo original permanecerá em um diretório temporário e o caminho será retornado na mensagem de erro.

Campos Disponíveis

Campo	Tipo	Descrição
Diretório atual	string	Caminho de onde o arquivo será movido.
Diretório destino	string	Caminho de destino dentro do mesmo servidor SFTP ou em outro servidor conectado.
Nome do arquivo	string	Nome do arquivo original que será movido.
Novo nome do arquivo (opcional)	string	Nome alternativo para renomear o arquivo ao movê-lo.
Sobrescrever arquivo existente	bolean	Define se o arquivo de destino deve ser sobrescrito caso já exista.

✅ Exemplo de Resposta de Sucesso

{
  "file": "example.txt",
  "path": "/destination/folder/",
  "success": true
}

💡 Dica: Caso o arquivo tenha sido renomeado, o campo `"file"` refletirá o novo nome.

❌ Exemplo de Erro com Falha no Rollback

{
  "code": "sftp-move-file",
  "message": "erro ao mover arquivo via SFTP: error during rollback, need manual intervention: file does not exist The original file is at: /tmp/8a7fc369-9ab6-476c-9ec0-85116f5135dd/example.txt"
}

⚠️ Nota: A mensagem de erro inclui o caminho temporário onde o arquivo original está armazenado, caso o rollback falhe.

Exemplos de Parametrização

Mover arquivo

Mover e renomear arquivo

Mover arquivo com sobrescrita habilitada (Sem renomear)

Mover e renomear arquivo com sobrescrita habilitada

Boas Práticas

Validar paths de origem e destino antes da operação.

Evitar nomes duplicados quando a sobrescrita estiver desativada.

Monitorar o diretório temporário em caso de falhas de rollback.