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).

Connect utiliza el acceso de Office Banking para autenticar y consultar cuentas. La conexión no requiere que mantengas abierto un navegador ni un emulador.

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.

Los tres textos del movimiento

Connect conserva por separado los textos que entrega Santander:

descripcionAmpliada se lee de la respuesta cifrada ya guardada: no requiere otro login ni una nueva sincronización si ese texto ya está disponible. Devuelve null cuando falta o está vacío. No reemplaza la glosa ni la observación, no se deduce del número de documento y no se usa para identificar la contraparte. La respuesta cruda del banco no se expone.

observacion devuelve null cuando no hay texto disponible o el movimiento histórico todavía no se ha enriquecido con este campo. Una nueva sincronización del período actualiza los movimientos existentes sin duplicarlos y recupera las observaciones pendientes que estén presentes en la respuesta cifrada guardada de cada movimiento histórico. No modifica sus montos ni inventa observaciones que el banco no informó.

Contraparte de un movimiento

movimientos.consultar incluye counterparty con los campos name, rut, bank y account, junto con counterpartySource. Se derivan al leer los textos ya sincronizados: no requieren otro login ni una migración. Los movimientos históricos que aún no tengan observacion deben volver a sincronizarse para derivar el RUT desde ese campo.

Cuando un formato soportado permite atribuir el RUT a la contraparte sin ambigüedad y su dígito verificador es válido, counterparty.rut lo entrega sin puntos, con guion y DV en mayúscula. La procedencia es "descripcion" si salió de la glosa o "observacion" si salió de observacion. Los tres textos conservan su contenido completo; la respuesta cruda del banco no se expone.

Ejemplo con un RUT sintético:

{
  "counterparty": {
    "name": null,
    "rut": "12345678-5",
    "bank": null,
    "account": null
  },
  "counterpartySource": "observacion"
}

name, bank y account permanecen en null hasta contar con formatos respaldados para extraerlos. numeroCuenta sigue siendo la cuenta conectada, no la cuenta de destino de una transferencia.

Los datos ambiguos o de formatos no soportados quedan en null. Si no se puede derivar contraparte, sus cuatro campos y counterpartySource son nulos: eso no demuestra que el banco nunca informe el dato. La cobertura depende del texto que entrega Santander y puede variar entre movimientos.

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"]}}'

Esta ruta y el body del ejemplo sí corresponden a la tool santander_empresas.conexion.sincronizar. El header X-Connect-Connection es obligatorio: usa el id de una conexión Santander, que puedes obtener con GET /v1/connections. No uses el id de una conexión SII u otro banco. Para pedir agosto y septiembre por la API de control, usa esa conexión Santander con {"periodos":["2026-08","2026-09"],"alcances":["movimientos"]}; no envuelvas ese cuerpo en input. Pedir saldos de esos meses cerrados no reconstruye saldos históricos.

La llamada encola el trabajo. El resultado incluye estado: "encolado" y un jobId; consulta ese job para conocer los alcances completados y recordsSynced. Un trabajo encolado todavía no acredita una sincronización.

{
  "data": {
    "periodo": "2026-08",
    "estado": "encolado",
    "jobId": "sjb_...",
    "yaEnCurso": false
  },
  "meta": { "request_id": "req_...", "tool_id": "santander_empresas.conexion.sincronizar", "plane": "read" }
}

Cada sincronización obtiene una sesión nueva y comparte el login entre los alcances solicitados. 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 termina en cero con su explicación en detalle. El resultado por alcance se lee en outcomes de GET /v1/syncs/{jobId}, en la API de control.

Verdades operativas

Una sesión por sincronización

Connect inicia sesión, verifica la empresa autorizada y recorre las cuentas y páginas de movimientos. Al terminar solicita el cierre al banco y elimina el material de sesión local. No conserva tokens para la siguiente sincronización.

Verificar y sincronizar

conexion.verificar comprueba el login y la autorización de la empresa sin persistir datos de negocio. conexion.sincronizar obtiene los saldos y movimientos y los guarda en Connect. Las consultas leen esos datos persistidos, sin abrir otra sesión bancaria.

Paginación y lecturas parciales

El cursor del banco determina si quedan páginas. Si el cursor se repite, se agota el presupuesto o una respuesta cambia de forma, el alcance no se declara completo. El resultado informa el fallo o la lectura parcial para que un cero no se confunda con ausencia de actividad.

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. Si el banco no informa la dirección, type permanece nulo: no se deduce del signo de un importe positivo. saldo es el saldo arrastrado tras el movimiento: conserva su propio signo.

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

La identidad usa la cuenta y el identificador textual del movimiento informado por el banco; el período se deriva de su fecha contable. Volver a sincronizar actualiza la misma fila, incluso si ya se había importado desde Office Banking.

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.