SFTP Connect

SFTP Connect

Tipo: sftp-connect  ·  Paquete: SFTP Activities v1.1.0  ·  Salida: ZoanSftpSession

Conecta a un servidor SFTP y devuelve una sesión que comparten las demás actividades. Es el punto de partida de cualquier transferencia: te autenticas una vez y haces todas las operaciones por la misma conexión.

Cómo funciona

Conecta a host:port (puerto 22 por defecto) con el username y la autenticación elegida:

• Clave privada: si privateKeyPath tiene valor, se carga ese archivo de clave (con privateKeyPassphrase si está cifrada) y se autentica con él; password se ignora.
• Contraseña: si no hay privateKeyPath, se usa password.

Antes de autenticarse comprueba la huella del servidor (ver Huella del servidor):

• Con hostKeyFingerprint: si la huella que presenta el servidor no es esa, la conexión se rechaza y no se envían credenciales.
• Sin hostKeyFingerprint: se acepta el servidor y el log muestra un aviso con su huella (SHA256:…) para que la copies al parámetro.

Dos modos:

• Con body: las actividades dentro heredan la sesión; al terminar se cierra sola, también si una actividad del body falla.
• Sin body: devuelve la sesión como salida; pásala como session a las actividades y ciérrala con SFTP Close.

Parámetros requeridos

Parámetro	Tipo	Por defecto	Descripción
host	string	—	Servidor SFTP (nombre o IP).
username	string	—	Usuario SSH.

Parámetros opcionales

Parámetro	Tipo	Por defecto	Descripción
port	int	22	Puerto SSH. Un valor que no sea un entero se toma como 22.
password	credential	—	Contraseña, para autenticación por contraseña. Usa credential("nombre")["password"]. Obligatoria si no das privateKeyPath.
privateKeyPath	string	—	Ruta local al archivo de clave privada (.pem / formato OpenSSH), para autenticación por clave.
privateKeyPassphrase	credential	—	Frase de la clave privada, solo si la clave está cifrada.
hostKeyFingerprint	string	—	Huella SHA256 esperada del servidor, como la muestra ssh-keygen -lf (ej. "SHA256:jK3Qe7lY0b6n1tXrA9wFZ2hVcM5pD8uS4oGiE0yT1aQ"). También acepta la línea completa de ssh-keygen o el valor sin SHA256:. Si no coincide, la conexión se rechaza. Vacío: se acepta el servidor y su huella queda en el log. Desde la versión 1.1.0.

Sub-flujos

body

Opcional. Actividades que se ejecutan con esta conexión; la heredan sin indicar session. Al salir (con éxito o con error) la conexión se cierra. Si el body está vacío, la actividad devuelve la sesión como salida.

Salida

• Sin body: devuelve un ZoanSftpSession. Pásalo como session a las demás actividades y ciérralo con SFTP Close.
• Con body: no devuelve ningún valor (la sesión solo existe dentro del body).

Errores comunes

Mensaje	Causa y solución
'host' es obligatorio. / 'username' es obligatorio.	Falta el parámetro o la expresión dio null.
Parameter 'password' is of type 'credential' but the value was null. Verify the credential exists in the configured store.	No diste privateKeyPath ni una contraseña válida (o la credencial no existe). Indica uno de los dos métodos.
Error de autenticación SSH (permiso denegado)	Usuario, contraseña o clave incorrectos, o el servidor no acepta ese método. Confírmalo con el administrador del servidor.
Error al leer el archivo de clave	privateKeyPath no existe, el formato no es compatible o la clave está cifrada y falta (o es incorrecta) privateKeyPassphrase.
La huella del servidor … no coincide con la esperada: se esperaba … y el servidor presentó ….	El servidor presentó otra llave. Puede ser un intermediario en la red: no lo ignores. Si el administrador confirma que cambió la llave, actualiza hostKeyFingerprint.
'hostKeyFingerprint' no es una huella SHA256. …	El valor no tiene la forma SHA256: + 43 caracteres. Cópialo tal como aparece en el aviso del log o en ssh-keygen -lf.
Error de conexión (host desconocido, conexión rechazada o tiempo agotado)	Host o puerto equivocados, o un firewall bloquea el puerto desde la máquina del robot. Envuélvelo en un Retry si el servidor tiene cortes puntuales.

Ejemplo

Con contraseña, descargando dentro del body:

SFTP Connect   host = "sftp.proveedor.com"   username = "zoan"   password = credential("sftp-proveedor")["password"]
 └─ body:
      SFTP Download   remotePath = "/salida/reporte.csv"   localPath = "C:/descargas/reporte.csv"   → output: archivo
      Read CSV   path = archivo   → output: datos

Con clave privada cifrada, guardando la sesión en una variable:

SFTP Connect   host = "sftp.banco.com"   port = 2222   username = "integracion"
               privateKeyPath = "C:/claves/integracion.pem"   privateKeyPassphrase = credential("clave-sftp")["password"]
               hostKeyFingerprint = "SHA256:jK3Qe7lY0b6n1tXrA9wFZ2hVcM5pD8uS4oGiE0yT1aQ"
               → output: sftp
SFTP Upload    session = sftp   localPath = "C:/salida/lote.csv"   remotePath = "/entrada/lote.csv"
SFTP Close     session = sftp

Actividades relacionadas

• SFTP Close — cerrar la conexión (modo sin body).
• SFTP Upload / SFTP Download — transferir archivos.