# Santander Empresas

> Saldos y movimientos de Banco Santander Empresas, sincronizados a la caché de Connect. El desafío de navegador del portal lo resuelve la sincronización, no tú.



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 [#qué-necesitas-para-conectar]

En el [enlace de conexión](/docs/empezar/conectar) la persona entrega la **clave de banca en línea** del portal Office Banking, 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 Santander.             |
| RUT de la empresa | La empresa que esta conexión va a leer.              |

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 [#los-alcances]

| Alcance       | Qué trae                                                                      | Tool que lo lee                            |
| ------------- | ----------------------------------------------------------------------------- | ------------------------------------------ |
| `saldos`      | El saldo contable y el disponible de cada cuenta, como una foto por día       | `santander_empresas.saldos.consultar`      |
| `movimientos` | Los movimientos de la cartola del período, con descripción y saldo arrastrado | `santander_empresas.movimientos.consultar` |

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

## Sincronizar [#sincronizar]

```bash
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):

```json
{
  "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](/docs/api-control).

## Verdades operativas [#verdades-operativas]

### El portal exige un desafío de navegador [#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 [#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 [#conexionverificar-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 [#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 [#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 [#errores-que-vas-a-ver]

| Código                               | Qué significa                                                                      | Qué hacer                                                                                            |
| ------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `409 connection_session_pending`     | No hay una sesión de portal acuñada y esta llamada no puede acuñarla.              | Ejecuta la sincronización de la conexión (ella acuña la sesión) o espera la programada, y reintenta. |
| `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`                | La conexión está en uso o el servicio alcanzó temporalmente su capacidad.          | Espera unos segundos y reintenta. No reconectes ni vuelvas a ingresar credenciales.                  |
| `502 upstream_error`                 | El banco (o el camino hasta él) falló de forma transitoria.                        | Reintenta más tarde. Si persiste, el problema está del lado del banco.                               |

El envelope de cada código está en el [catálogo de errores](/docs/operar/errores).

## Próximos pasos [#próximos-pasos]

* Las cuatro tools, con contrato completo: [referencia de `santander_empresas`](/docs/referencia/santander_empresas).
* La separación entre escribir la caché y leerla: [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar).
* Saber de cada sync sin preguntar: [Webhooks](/docs/operar/webhooks).