Santander Empresas

Con la clave de banca en línea de la empresa, santander_empresas sincroniza saldos y movimientos de Banco Santander Empresas hacia el plano persistido de Connect, y dos tools de consulta los leen de esa caché sin esperar al banco. El conn_… de la conexión dice qué empresa lees y viaja en toda llamada (en REST, el header X-Connect-Connection).

Santander tiene la misma particularidad que BICE: su portal protege el login con un desafío de navegador. Connect lo resuelve por ti, con las reglas que se explican abajo.

Qué necesitas para conectar

En el enlace de conexión la persona entrega la clave de banca en línea del portal Office Banking, en tres campos:

El acceso solo lee, y desde el dashboard se revoca en el acto. La clave no pasa por tu código: la entrega quien la tiene, en un enlace que sirve una sola vez.

Los alcances

Qué alcances quedan habilitados se decide por conexión, desde el dashboard.

Sincronizar

curl -X POST https://connect.emisso.ai/api/v1/tools/santander_empresas.conexion.sincronizar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"periodo":"2026-08","alcances":["saldos","movimientos"]}}'

Respuesta (recortada):

{
  "data": {
    "periodo": "2026-08",
    "results": [
      { "alcance": "saldos", "status": "ok", "recordsSynced": 1 },
      { "alcance": "movimientos", "status": "ok", "recordsSynced": 12, "cuentasConsultadas": 1 }
    ]
  },
  "meta": { "request_id": "req_...", "tool_id": "santander_empresas.conexion.sincronizar", "plane": "read" }
}

El primer login abre el desafío de navegador y puede tardar cerca de un minuto; las sincronizaciones siguientes reutilizan la sesión de portal vigente y son más rápidas. cuentasConsultadas acompaña a movimientos para que un cero sea interpretable: cero registros con una cuenta consultada es un dato del banco; cero registros con cero cuentas significa que ni siquiera se llegó a preguntar, y el campo detalle lo dice en palabras.

Como en los demás bancos, saldos es una foto del momento: en un período que no es el corriente devuelve cero con su explicación en detalle. Y el login no exige esperarlo en línea: el trabajo se encola por la API de control.

Verdades operativas

El portal exige un desafío de navegador

El login de Santander corre detrás de un desafío anti-bot que no se puede resolver con HTTP puro. Cuando conexion.sincronizar necesita entrar, abre un navegador remoto solo para ese login y acuña una sesión de portal; desde ahí, todos los datos viajan por HTTP normal, igual que en los demás bancos. La sesión acuñada se reutiliza entre sincronizaciones mientras siga vigente (25 minutos por defecto), y se invalida sola cuando rotas la credencial.

connection_session_pending: qué es y qué hacer

Solo la sincronización puede abrir ese navegador. Cualquier otra tool que necesite sesión de portal responde 409 connection_session_pending cuando no hay una vigente, en vez de dejarte esperando un login largo. El código es reintentable: ejecuta santander_empresas.conexion.sincronizar (ella acuña la sesión) o espera la sincronización programada, y reintenta la llamada original.

conexion.verificar no abre navegador

La verificación de credenciales es deliberadamente barata: con una sesión de portal vigente verifica de inmediato, y sin sesión devuelve connection_session_pending sin tocar al banco. Un verificar nunca dispara el login de navegador; si lo que quieres es acuñar la sesión, el camino es sincronizar.

Los montos son números, con la convención del libro del banco

monto es la magnitud sin signo; type dice si la plata sale (cargo) o entra (abono) según el libro del banco, y display trae ese monto ya formateado a la chilena, con su signo. saldo es el saldo arrastrado tras el movimiento: es un balance, no lleva type y conserva su propio signo.

El período se pide, no se guarda en la identidad

Pedir el mismo movimiento con otro período no crea una fila nueva: el período es cómo lo pediste, no una propiedad del movimiento. Por eso re-sincronizar es seguro y nunca infla los totales.

Errores que vas a ver

El envelope de cada código está en el catálogo de errores.

Próximos pasos

• Las cuatro tools, con contrato completo: referencia de santander_empresas.
• La separación entre escribir la caché y leerla: Sincronizar y consultar.
• Saber de cada sync sin preguntar: Webhooks.