API de Banco Security: transferencias, nóminas y saldos

Transferencias, nóminas de pago, saldos y movimientos del portal de Banco Security, servidos al instante desde la caché de Connect.

banco_security sincroniza cuatro alcances del portal de empresas de Banco Security hacia el plano persistido de Connect: transferencias TEF, nóminas de pago masivas, saldos y movimientos de cuenta corriente. El login usa la clave de la empresa; cinco tools de consulta leen esa caché al instante. Cada llamada identifica a la empresa por el conn_… de su conexión (en REST, el header X-Connect-Connection).

Qué necesitas para conectar

La Clave de banca en línea del portal entra por el enlace de conexión, en tres campos:

Campo	Qué es
RUT de acceso	El RUT de la persona que inicia sesión en el portal.
Clave	Su clave de banca en línea de Banco Security.
RUT de la empresa	La empresa que esta conexión va a leer.

Que los dos RUT vayan separados tiene una razón: quien entra al portal casi nunca es la empresa. Connect usa ese acceso solo para leer y revocarlo desde el dashboard es inmediato; la clave entra por el enlace de un solo uso, directo de quien la tiene, sin cruzar tu código.

Los alcances

Alcance	Qué trae	Tool que lo lee
`transferencias`	Las TEF enviadas y recibidas del período, con contraparte, número de transacción y quién la creó y aprobó	`banco_security.transferencias.consultar`
`nominas`	Las nóminas de pago masivas: cabeceras por un lado, líneas de pago por otro	`banco_security.nominas.consultar` y `banco_security.nomina_pagos.consultar`
`saldos`	Los tres saldos de cada cuenta (contable, disponible y provisorio), como una foto por día	`banco_security.saldos.consultar`
`movimientos`	Los movimientos de cuenta corriente de cualquier período sincronizado	`banco_security.movimientos.consultar`

Cada conexión habilita sus alcances desde el dashboard; consultar uno apagado responde 403 alcance_not_enabled.

Sincronizar

Varios alcances en la misma llamada comparten un único login contra el banco (cerca de 90 segundos); el conector los ejecuta en el orden interno que la sesión del portal exige, así que no importa cómo los ordenes tú.

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

Respuesta (recortada):

{
  "data": {
    "periodo": "2026-07",
    "results": [
      { "alcance": "transferencias", "status": "ok", "recordsSynced": 18 },
      {
        "alcance": "saldos",
        "status": "ok",
        "recordsSynced": 0,
        "detalle": "Los saldos son una foto del momento, no del período, así que solo se sincronizan en el período corriente. Este cero NO significa que la cuenta no tenga saldo: pediste 2026-07; pide 2026-08 para obtenerlo."
      },
      { "alcance": "movimientos", "status": "ok", "recordsSynced": 214 }
    ]
  },
  "meta": { "request_id": "req_...", "tool_id": "banco_security.conexion.sincronizar", "plane": "read" }
}

Con un período ya cerrado, saldos devuelve cero con su detalle: la foto del saldo existe solo para el período corriente. Los otros alcances cubren cualquier período.

El sync también se puede encolar por la API de control para no quedarse esperando el login; el resultado llega por webhook.

Verdades operativas

Las nóminas van en dos niveles

banco_security.nominas.consultar devuelve solo las cabeceras, cada una con su idNomina, su monto total y numRegistros, la cantidad de líneas que contiene. Las líneas de pago (a quién, cuánto, a qué cuenta, con qué glosa y si fue rechazado) se piden aparte con banco_security.nomina_pagos.consultar, pasando ese idNomina. Separarlas no es capricho: hay nóminas de más de mil líneas, y numRegistros existe para que dimensiones antes de pedir el detalle.

Dos cartolas del banco, una sola caché

El banco sirve el mes en curso y los meses cerrados por dos rutas distintas de su portal. Eso es interno del conector: el período que pides elige la ruta, las dos escriben la misma tabla con la misma identidad por movimiento, y un mes que aparezca en ambas no se duplica. Los resultados de movimientos.consultar se pueden sumar sin miedo.

El número de transacción es texto

numeroTransaccion viene como string a propósito: el banco emite números de 14 dígitos, que no caben en un entero de 32 bits. Trátalo como identificador y no lo conviertas a número.

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

monto es la magnitud sin signo; type dice si la plata entra (debit) o sale (credit) según el libro del banco, que invierte lo que una cartola muestra; y display trae el monto ya formateado a la chilena, signo incluido. Una nómina siempre es un desembolso, así que sus filas salen credit. Los saldos no llevan type: conservan su propio signo, y la misma empresa puede tener cuentas en pesos y en dólares, cada una con su currency.

Errores que vas a ver

Código	Qué significa	Qué hacer
`428 connection_credential_required`	La conexión no tiene una credencial viva: nunca se vinculó, venció o fue revocada.	Emite un enlace de reconexión y pide la clave de nuevo. No reintentes con la credencial anterior.
`409 connection_busy`	Otra operación tiene tomado el candado de esta conexión.	Espera unos segundos y reintenta: el candado se suelta solo.
`409 connection_sync_in_progress`	Ya corre una sincronización de esa conexión para ese período.	Espera a que termine, o consulta directamente: puede que ya haya datos.
`403 alcance_not_enabled`	La conexión no tiene habilitado el alcance que la tool pide.	Habilítalo en la conexión desde el dashboard, o quítalo del input de la sincronización.

Cada código, con su envelope completo, está en el catálogo de errores.

Próximos pasos

Las siete tools con su contrato: referencia de banco_security.
El modelo de dos pasos detrás de cada .consultar: Sincronizar y consultar.
Que cada sync avise al terminar: Webhooks.

Banco Security

On this page