Sistemas

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

En el enlace de conexión la persona entrega la Clave de banca en línea del portal, en tres campos:

CampoQué es
RUT de accesoEl RUT de la persona que inicia sesión en el portal.
ClaveSu clave de banca en línea de BICE.
RUT de la empresaLa 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

AlcanceQué traeTool que lo lee
saldosEl saldo contable y el disponible de cada cuenta, como una foto por día (cómo leer el saldo de una cuenta)bice_empresas.saldos.consultar
movimientosLos movimientos de la cartola del período, con descripción, documento y saldo arrastradobice_empresas.movimientos.consultar

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

Sincronizar

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

{
  "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 explica la espera, los errores y el caso yaEnCurso: true con jobId: null.

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

"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

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

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

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

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

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

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

CódigoQué significaQué hacer
409 connection_session_pendingEl 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_requiredLa 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_busyLa 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_errorEl 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.

Próximos pasos

En esta página