BancoEstado Empresas

banco_estado sincroniza dos alcances del portal de BancoEstado Empresas hacia el plano persistido de Connect: los saldos de cuenta corriente y los movimientos de la cartola. El login usa los mismos tres datos con que se entra a la banca en línea; dos 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).

Una sola sesión activa por usuario

Es la particularidad que gobierna todo lo demás, y conviene saberla antes de conectar:

BancoEstado admite una sola sesión activa por usuario. Mientras corre una sincronización no vas a poder entrar al portal, y si estás dentro del portal la sincronización va a fallar. Conviene dejarla agendada fuera del horario en que usas la banca en línea.

Cerrar el navegador no libera la sesión: el portal la mantiene abierta unos minutos más. Por eso Connect cierra sesión siempre al terminar, y por eso una sincronización que se cruza con una persona dentro del portal devuelve 409 connection_session_pending en vez de un error genérico.

Qué necesitas para conectar

La clave de banca en línea de empresas entra por el enlace de conexión, en tres campos:

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

El segundo factor de BancoEstado (BE Pass, BE Face) autoriza operaciones, como transferencias y nóminas, no la consulta: una conexión de solo lectura no lo dispara.

Los alcances

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

Sincronizar

Los dos alcances en la misma llamada comparten un único login contra el banco. Aquí eso no es una optimización: como el banco admite una sola sesión por usuario, un segundo login dentro del mismo trabajo sería un rechazo.

curl -X POST https://connect.emisso.ai/api/v1/tools/banco_estado.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": 2 },
      { "alcance": "movimientos", "status": "ok", "recordsSynced": 137 }
    ]
  },
  "meta": { "request_id": "req_...", "tool_id": "banco_estado.conexion.sincronizar", "plane": "read" }
}

Con un período ya cerrado, saldos devuelve cero con un detalle que lo explica: la foto del saldo existe solo para el período corriente, y ese cero no significa que la cuenta esté vacía. movimientos cubre cualquier período sincronizado.

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

Los saldos son una foto por día

Cada fila de saldos.consultar es el saldo de una cuenta en un día (observedDay), con la hora en que el banco la reportó. Sincronizar dos veces el mismo día actualiza esa foto en vez de agregar otra. Las retenciones vienen desglosadas (a un día, a dos días, y el resto agrupado), más el total.

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 (credit) o entra (debit) según el libro del banco, que invierte lo que una cartola muestra; y display trae el monto ya formateado a la chilena, con su signo. Es el mismo contrato de los otros tres bancos de Connect, así que un consumidor que ya lee uno lee este sin cambios.

saldo es distinto: es el saldo arrastrado tras el movimiento, o sea un balance. No lleva type y conserva su propio signo, porque un sobregiro es negativo.

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: las dos escriben la misma tabla con la misma identidad por movimiento, así que un mes que aparezca en ambas no se duplica y los resultados se pueden sumar sin miedo. El campo origen de cada fila dice por cuál se trajo.

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

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

Próximos pasos

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