# Santander Empresas > Saldos y movimientos de Banco Santander Empresas, sincronizados y disponibles para consulta en Connect. 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 [#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, descripción ampliada y observación cuando el banco las informa, y saldo arrastrado | `santander_empresas.movimientos.consultar` | Qué alcances quedan habilitados se decide por conexión, desde el dashboard. ### Los tres textos del movimiento [#los-tres-textos-del-movimiento] Connect conserva por separado los textos que entrega Santander: | Campo | Contenido | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `descripcion` | La glosa del movimiento que aparece en la cartola. | | `descripcionAmpliada` | El texto literal del campo bancario `CodigoAmp`, como `Depósito en efectivo` o `Cheque Depositado`. Es una etiqueta informada por Santander, no una clasificación de Connect. | | `observacion` | El texto complementario de `Observacion`, que puede incluir detalles de la operación. No se identifica automáticamente como el mensaje que escribió quien transfirió. | `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 [#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: ```json { "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 [#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"]}}' ``` 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](/docs/api-control#pedir-agosto-y-septiembre-y-ver-su-estado) 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. ```json { "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](/docs/api-control). ## Verdades operativas [#verdades-operativas] ### Una sesión por sincronización [#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 [#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 [#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 [#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 [#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 [#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` | 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).