SFTP Activities

Versión: 1.1.0 · ID: zoan-packages-sftp · Autor: Zoan Software

El paquete SFTP transfiere archivos de forma segura con un servidor remoto mediante el protocolo SFTP (SSH File Transfer Protocol). Es muy usado en integraciones entre empresas: subir archivos a un servidor (un lote de facturas para un proveedor), descargar archivos que dejan ahí (reportes de un banco), o gestionar carpetas remotas. No necesita ningún cliente instalado en la máquina del robot, así que funciona también en ejecución desatendida.

Concepto 1: la sesión

Todas las operaciones trabajan sobre una sesión que abres con SFTP Connect y compartes con las demás actividades. Una sola conexión sirve para todas las transferencias, sin volver a autenticarse en cada archivo:

Con body: las actividades dentro heredan la sesión; al terminar (también si algo falla) la conexión se cierra sola.
Sin body: guardas la sesión en una variable, la pasas como session y la cierras con SFTP Close.

A diferencia de los paquetes de correo, aquí la sesión es obligatoria: una actividad SFTP fuera del body de Connect y sin session falla con 'session' debe ser una ZoanSftpSession.

SFTP Connect   host = "sftp.proveedor.com"   username = "zoan"   password = credential("sftp-proveedor")["password"]
 └─ body:
      SFTP Upload   localPath = rutaLocal   remotePath = "/entrada/factura.xml"

Concepto 2: autenticación

SFTP admite dos formas de autenticarse (elige una en SFTP Connect):

Método	Cómo
Contraseña	Parámetro `password` con una credencial — `credential("sftp-proveedor")["password"]`.
Clave privada	Parámetro `privateKeyPath` con la ruta a tu clave (`.pem` / OpenSSH) en la máquina del robot, y `privateKeyPassphrase` si está cifrada. Si das `privateKeyPath`, se usa la clave y se ignora `password`.

Huella del servidor

La huella (host key) identifica al servidor. Indícala en el parámetro hostKeyFingerprint de SFTP Connect y el robot solo se conecta a ese servidor: si otro se hace pasar por él (un intermediario en la red), la conexión se rechaza antes de enviar el usuario o la contraseña. Desde la versión 1.1.0.

Cómo obtenerla: conéctate una vez sin huella; el log muestra un aviso con la huella recibida (SHA256:…), cópiala al parámetro. También te la puede dar el administrador del servidor (ssh-keygen -lf sobre la llave pública del servidor).
Sin huella: se acepta el servidor que responda, como en versiones anteriores, y la huella queda en el log.
Si el servidor cambia su llave de forma legítima, la conexión falla con un error que muestra la huella esperada y la recibida: actualiza el parámetro.

Rutas remotas

Las rutas del servidor usan barras /: /entrada/datos.csv, /salida/reportes/. Una ruta sin / inicial es relativa a la carpeta de inicio del usuario en el servidor. No las confundas con las rutas locales (de la máquina del robot), que van en localPath.

Actividades

Sesión

Actividad	Tipo	Salida	Qué hace
SFTP Connect	`sftp-connect`	`ZoanSftpSession`	Conecta al servidor SFTP
SFTP Close	`sftp-close`	—	Cierra la conexión

Transferir

Actividad	Tipo	Salida	Qué hace
SFTP Upload	`sftp-upload`	`string`	Sube un archivo local al servidor
SFTP Download	`sftp-download`	`string`	Descarga un archivo del servidor

Gestionar archivos y carpetas

Actividad	Tipo	Salida	Qué hace
SFTP List Directory	`sftp-list`	`List<object>`	Lista archivos y carpetas remotas
SFTP Exists	`sftp-exists`	`bool`	¿Existe un archivo/carpeta?
SFTP Move / Rename	`sftp-move`	`string`	Mueve o renombra un archivo remoto
SFTP Delete	`sftp-delete`	—	Elimina un archivo remoto
SFTP Create Directory	`sftp-mkdir`	—	Crea una carpeta remota

Siguientes pasos

SFTP Connect — conectarse al servidor.
SFTP Download / SFTP Upload — transferir archivos.
Files — gestionar los archivos locales.