# BICE Empresas

> Saldos y movimientos de BICE Empresas, sincronizados a la caché de Emisso.



Con la clave de la empresa, `bice_empresas` sincroniza saldos y movimientos de BICE Empresas hacia el plano persistido de Emisso, 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`).

La primera sincronización de BICE tarda más que en otros bancos; abajo se explica qué esperar.

## 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, 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 BICE.                  |
| 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 ([cómo leer el saldo de una cuenta](/docs/conceptos/sincronizar-consultar#leer-el-saldo-de-una-cuenta)) | `bice_empresas.saldos.consultar`      |
| `movimientos` | Los movimientos de la cartola del período, con descripción, documento y saldo arrastrado                                                                                        | `bice_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/bice_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 de encolado (`200`, metadatos recortados):

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

La llamada acepta el trabajo y responde antes del login. Sigue `data.jobId` con
`GET /api/v1/syncs/{jobId}` hasta que termine y revisa los alcances en `data.outcomes`:
`succeeded` puede incluir alcances parciales o fallidos. La [guía de seguimiento](/docs/conceptos/sincronizar-consultar#cómo-sabes-que-terminó)
explica la espera, los errores y el caso `yaEnCurso: true` con `jobId: null`.

Para esta llamada, `outcomes` queda así (recortado):

```json
"outcomes": [
  { "alcance": "saldos", "status": "ok", "recordsSynced": 1 },
  { "alcance": "movimientos", "status": "ok", "recordsSynced": 18, "cuentasConsultadas": 1 }
]
```

La primera sincronización puede tardar cerca de un minuto; las siguientes suelen ser más rápidas. `cuentasConsultadas` acompaña a `movimientos`, pero debe leerse junto al `status`, `error`, `fueraDeVentana` y `detalle` del alcance: una cuenta consultada con cero registros no demuestra por sí sola que no tenga movimientos. Con cero cuentas ni siquiera se llegó a preguntar.

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

### Capturas incompletas o contradictorias [#capturas-incompletas-o-contradictorias]

Emisso valida todas las páginas de una cuenta antes de publicar sus movimientos. Si faltan páginas, se repiten operaciones o los conteos, totales o monedas no concuerdan, conserva la evidencia y los movimientos anteriores de esa cuenta, sin publicar filas nuevas de ella. Las otras cuentas cuya captura sea válida pueden avanzar.

En el recorrido legado de las cartolas provisionales, el banco puede declarar un intervalo distinto en cada página. Emisso puede publicar sus movimientos cuando esos extremos coinciden con la fecha mínima y máxima de cada página, se conserva el orden descendente y el resto de la cabecera y los totales globales concuerdan. Esas fechas describen las páginas observadas: pueden compartir días o dejar huecos y no acreditan una ventana global ni todo el mes solicitado.

En esa forma, el manifiesto conserva el rechazo por falta de cobertura global, aunque los movimientos válidos se publiquen. Esos registros no autorizan retiros ni reactivaciones de versiones anteriores. La reconciliación requiere una captura aceptada para la cuenta, moneda y fecha; una captura rechazada de la misma cuenta y moneda la bloquea.

Las capturas ya rechazadas conservan su estado y su ventana original. Una nueva sincronización genera su propio manifiesto. Publicar movimientos válidos no aplica la reparación de versiones acumuladas descrita más abajo.

Las fallas estructurales informan `status: "failed"` y `error: "movimientos_truncated"`. La falta de cobertura global por sí sola no produce ese error cuando las operaciones son estructuralmente válidas. `recordsSynced` cuenta los registros publicados y puede ser mayor que cero si otra cuenta sí se leyó correctamente. Un job `succeeded` con un outcome fallido sigue teniendo un alcance fallido; un rechazo con cero registros no es una cartola vacía acreditada.

## Versiones de movimientos y recarga [#versiones-de-movimientos-y-recarga]

El `id` de `bice_empresas.movimientos.consultar` identifica una **versión observada** del movimiento. Su huella incluye el saldo contable: si BICE recalcula ese saldo, la misma operación puede tener otro ID. Documento, glosa, fecha y monto tampoco constituyen una llave única; dos operaciones legítimas pueden coincidir en esos datos.

La conciliación de cambios de saldo se habilita por conexión después de revisar la evidencia y reparar las versiones acumuladas. Una vez habilitada, las capturas aceptadas sustituyen versiones comparables anteriores y la consulta entrega las vigentes, conservando movimientos gemelos legítimos. El despliegue por sí solo no acredita que una conexión ya esté reparada. Esta corrección no retira movimientos por ausencia ni resuelve cambios sustantivos de documento o glosa.

Si guardaste movimientos de una conexión afectada, coordina con soporte el alcance de la reparación antes de recargarlos:

1. Conserva un respaldo y revisa las referencias de tu sistema a los IDs anteriores.
2. Consulta todo el alcance corregido, con los mismos filtros, hasta recibir `cursor: null`. Incluye los períodos adyacentes que indique la revisión y deduplica por ID las versiones repetidas entre páginas o períodos.
3. Reemplaza de forma atómica la importación de ese alcance con la extracción completa. Añadirla mediante upsert por ID mantiene las versiones antiguas y no limpia los duplicados.
4. Verifica el conjunto importado y confirma la recarga con soporte.

## Antes de depender de los datos [#antes-de-depender-de-los-datos]

### La primera sincronización tarda más [#la-primera-sincronización-tarda-más]

Entrar a BICE toma cerca de un minuto, y solo `conexion.sincronizar` puede hacerlo. Las sincronizaciones siguientes suelen ser más rápidas. Si rotas la credencial, la siguiente vuelve a entrar desde cero.

### `connection_session_pending`: qué es y qué hacer [#connection_session_pending-qué-es-y-qué-hacer]

Solo la sincronización puede entrar a BICE. Cualquier otra tool que necesite ese acceso responde `409 connection_session_pending` cuando todavía no está listo, en vez de dejarte esperando. El código es reintentable: ejecuta `bice_empresas.conexion.sincronizar` o espera la sincronización programada, y reintenta la llamada original.

### `conexion.verificar` no reemplaza a la sincronización [#conexionverificar-no-reemplaza-a-la-sincronización]

`conexion.verificar` responde de inmediato si el acceso ya está listo; si no, devuelve `connection_session_pending` sin tocar al banco. Para comprobar una clave nueva, sincroniza.

### La cartola corre de fin de mes a fin de mes [#la-cartola-corre-de-fin-de-mes-a-fin-de-mes]

BICE no arma sus cartolas por mes calendario: la del período `2026-07` va del 30 de junio al 31 de julio. Por eso `movimientos.consultar` de un período puede incluir movimientos fechados en los últimos días del mes anterior. La misma versión observada conserva su ID entre rutas y ventanas; un saldo recalculado puede producir otra versión, como explica [Versiones de movimientos y recarga](#versiones-de-movimientos-y-recarga). Y no todos los meses están disponibles: cuando pides un período que el banco no ofrece, el sync lo marca con `fueraDeVentana: true` y un `detalle` que pide no confundirlo con «no hubo movimientos».

## Errores que vas a ver [#errores-que-vas-a-ver]

| Código                               | Qué significa                                                                      | Qué hacer                                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `409 connection_session_pending`     | El acceso a BICE todavía no está listo y esta llamada no puede prepararlo.         | Ejecuta la sincronización de la conexió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 `bice_empresas`](/docs/referencia/bice_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).


---

Esta página es parte de la documentación de Emisso. El índice completo, con cada página y su descripción, está en https://connect.emisso.ai/llms.txt. Esta misma página en HTML: https://connect.emisso.ai/docs/sistemas/bice-empresas.
