Sistemas

Banco de Chile Empresas

Saldos y cartolas en todas las monedas, con currency en cada fila, y movimientos de cuentas y tarjetas de Banco de Chile Empresas.

Consulta saldos, movimientos de cuentas y tarjetas de crédito y cartolas mensuales de Banco de Chile Empresas. Cada conexión corresponde a una empresa; en REST, indícala con el header X-Connect-Connection.

Consultas recomendadas: v2

Usa estas versiones en nuevas integraciones:

ToolVersiónQué obtienes
Saldos v2RecomendadaSaldos de todas las monedas disponibles, incluidas CLP y USD.
Cartolas v2RecomendadaCartolas de todas las monedas disponibles, filtrables por período, cuenta o emisión.

Cada fila incluye su currency y conserva los importes, signos y decimales originales. Puedes distinguir pesos y dólares sin convertirlos ni mezclarlos en un total. Las líneas de detalle de cartolas también están disponibles en USD, con sus decimales.

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 Banco de Chile.
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.

Si la clave ve varias empresas en el portal, crea una conexión por empresa. Cada una declara su propio «RUT de la empresa» y solo muestra los datos de esa empresa. Si la clave no tiene acceso a la empresa que declaraste, la conexión falla al crearse y te dice por qué.

Los alcances

AlcanceQué traeTool que lo lee
saldosSaldos disponible y contable, y línea de crédito, en CLP y USD, como una foto por día (cómo leer el saldo de una cuenta)bch_empresas.saldos.consultar_v2
movimientosLos movimientos de cuentas CLP y USD del período, con moneda, descripción, canal y saldo arrastradobch_empresas.movimientos.consultar
movimientos_tarjetasMovimientos pendientes y facturados de tarjetas, en CLP y USDbch_empresas.movimientos_tarjetas.consultar
cartolasLas cartolas mensuales oficiales en CLP y USD; líneas del extracto CLP y USD cuando están disponiblesbch_empresas.cartolas.consultar_v2 y bch_empresas.cartolas.detalle

Versiones anteriores: compatibilidad

Las v1 se mantienen ejecutables y devuelven solo CLP:

Versión anterior, se mantiene por compatibilidadVersión recomendada
Saldos v1Saldos v2
Cartolas v1Cartolas v2

Si hay otras monedas disponibles dentro de tus filtros, otrasMonedas.consultarEn señala la sucesora. Para incluirlas, cambia explícitamente la tool de tu integración a v2. Agrupa los totales por moneda: no sumes CLP y USD directamente.

Qué alcances quedan habilitados se decide por conexión, desde el dashboard. El gate de alcances rechaza la llamada entera si uno solo de los alcances pedidos no está habilitado: pedir ["saldos","movimientos","movimientos_tarjetas"] sobre una conexión que no habilitó movimientos_tarjetas no sincroniza los otros dos, sino que devuelve 403 alcance_not_enabled completo. Las conexiones anteriores a un alcance nuevo no lo reciben de forma implícita: se habilita desde /ajustes como cualquier otro alcance.

Sincronizar

curl -X POST https://connect.emisso.ai/api/v1/tools/bch_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","movimientos_tarjetas"]}}'

Respuesta de encolado (200, metadatos recortados):

{
  "data": {
    "periodo": "2026-08",
    "estado": "encolado",
    "jobId": "sjb_9f2kc0q8w1m4x7t3p6b5d",
    "yaEnCurso": false
  },
  "meta": {
    "request_id": "req_...",
    "tool_id": "bch_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": 2 },
  { "alcance": "movimientos", "status": "ok", "recordsSynced": 41 },
  { "alcance": "movimientos_tarjetas", "status": "ok", "recordsSynced": 18 }
]

Una sola sincronización cubre todos los alcances pedidos. 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. Habilita cada alcance antes de incluirlo; pedir uno deshabilitado rechaza la sincronización entera, no solo ese alcance.

Si el banco rechaza la consulta de movimientos, Emisso lo intenta cuenta por cuenta. Si logra completar alguna cuenta o recuperar movimientos, pero otra sigue rechazada, conserva los movimientos válidos y declara el alcance incompleto: el outcome lleva status: "failed", recordsSynced con la cantidad recuperada y el motivo respuesta_inesperada. El detalle identifica las cuentas rechazadas por moneda y últimos cuatro dígitos. Una cuenta rechazada no equivale a una cuenta sin movimientos; revisa siempre el outcome aunque ya haya filas disponibles para consultar.

Cuando el banco informa movimientos de cuentas provisorios sin hora, Emisso los deja fuera para evitar duplicarlos con su versión confirmada. Los demás movimientos se guardan; el módulo queda partial, con completo: false y el motivo movimientos_por_confirmar. El detalle indica cuántos quedaron fuera: se incorporan si el banco los vuelve a informar con hora mientras el período se siga leyendo. No se garantiza que eso ocurra antes de dejar de revisar ese mes. Los movimientos ya guardados se conservan.

Qué trae de las tarjetas

Con el alcance movimientos_tarjetas habilitado, cada tarjeta de crédito de la empresa trae sus compras no facturadas, sus fechas de facturación y sus estados de cuenta nacional e internacional. El estado nacional llega en CLP y el internacional en USD. No se entrega el número completo de la tarjeta: solo los últimos cuatro dígitos, cuando identifican la tarjeta sin ambigüedad, y una referencia estable.

Si no ves movimientos de tarjetas, o faltan los internacionales, revisa en los ajustes de la conexión, en Módulos de datos, que esté activo Movimientos de tarjetas (movimientos_tarjetas) y espera a que sincronice después de activarlo: las conexiones creadas antes de este alcance no lo reciben solas.

Los pendientes solo se consultan para el mes corriente, porque son una foto mutable. Los estados facturados sí se consultan por las fechas del período solicitado. Cuando una operación pasa de pendiente a facturada, la versión facturada prevalece y una sincronización posterior no puede degradarla de nuevo a pendiente.

Si el banco no entrega los estados de cuenta de una tarjeta, el alcance queda partial, con el motivo estados_cuenta_no_disponibles. Emisso guarda las compras no facturadas que sí obtuvo y conserva los movimientos anteriores; las demás tarjetas se siguen cargando. Consulta con tu ejecutivo de Banco de Chile para habilitar los estados de cuenta. En meses anteriores no se consultan las compras no facturadas actuales, por lo que ese parcial puede no traer registros nuevos.

Cartola Histórica oficial

Puedes leer las líneas del extracto mensual que Banco de Chile publica en Cartola Histórica, para cuentas en pesos chilenos (CLP) y en dólares (USD). Emisso descarga el archivo que ofrece el portal y conserva su orden, sus repeticiones, los cargos, los abonos, el saldo de cada línea y el número de documento cuando viene informado. No reconstruye el extracto a partir del feed de movimientos.

Cómo leerla desde tu integración

Los saldos y las cartolas conservan la moneda de la cuenta, sin convertir dólares a pesos. Una moneda o un formato todavía no soportados dejan el alcance incompleto; los datos recuperados de las otras cuentas se conservan. Revisa siempre el resultado de cada alcance.

  1. Habilita el alcance cartolas en la conexión y usa una credencial con el permiso bch_empresas:read.
  2. Sincroniza el mes que necesitas con bch_empresas.conexion.sincronizar, indicando alcances: ["cartolas"]. Sigue el job y revisa el outcome de ese alcance antes de importar. El contrato de seguimiento del trabajo y la guía de espera detallan sus estados, resultados por alcance y qué hacer si el trabajo ya estaba en curso.
  3. Lista los extractos guardados con bch_empresas.cartolas.consultar_v2. Conserva numeroCuenta, currency y fechaEmisionDay del extracto que necesitas.
  4. Pasa esos tres valores a bch_empresas.cartolas.detalle. Lee todas las páginas hasta que cursor sea null; admite hasta 200 líneas por página. Las consultas usan los datos guardados y no contactan al banco.

El Bearer de Emisso sigue siendo obligatorio al consultar. La etiqueta técnica Auth: none de esas tools solo indica que no necesitan iniciar sesión en el banco.

totalLineas indica cuántas líneas tiene el extracto y lineasLeidasEn cuándo se descargaron. Si cartola es null, ese extracto todavía no está guardado. Si hay cartola pero lineas es null, no hay líneas disponibles de ese extracto: no significa que esté vacío. Si lineas es una lista vacía, el banco emitió el extracto sin movimientos. La fecha de emisión identifica el extracto; no presupongas que todas sus operaciones tienen fecha dentro de ese mismo mes.

El mes solicitado se usa para buscar el índice de cartolas del banco entre el primer y el último día de ese mes. Revisa los extractos devueltos y elige por cuenta y fecha de emisión; no elijas el primero por su posición. Una lista vacía solo dice que no hay extractos guardados para ese filtro: revisa el resultado de la sincronización antes de atribuirle una causa.

Importarla sin duplicar lo que ya tienes

La cuenta, la moneda y la fecha de emisión identifican el extracto dentro de una conexión. En cartolas.detalle, indica currency: "USD" para consultar dólares; si omites la moneda, consulta CLP por compatibilidad. Si el extracto sólo existe en USD, omitir currency devuelve cartola: null; no lo presenta como pesos. Volver a sincronizarlo actualiza el mismo extracto. Una nueva lectura XLS invalida los cursores anteriores, aunque el archivo tenga las mismas líneas. Un cursor inválido responde HTTP 400 validation_error. Si ocurre al continuar un extracto y la cuenta y la emisión son correctas, descarta las páginas acumuladas y reinicia sin cursor; no mezcles dos lecturas ni reintentes indefinidamente. Si falla también sin cursor, revisa los parámetros. Completa el extracto antes de importar.

En tu ERP, trata la cartola como una unidad. Releerla no debe añadir otra copia de todas sus líneas. Si ya importaste movimientos de ese período, concílialos contra la cartola antes de cargar sus líneas como operaciones nuevas. Emisso mantiene ambos recursos separados y no deduplica operaciones entre ellos.

El archivo conserva los signos de cargo y abono; no supongas que ambos serán siempre positivos. Comprueba la secuencia de saldos con saldo anterior - cargo + abono y revisa cualquier diferencia antes de importar. El campo fecha del archivo no se equipara automáticamente a fechaMovimiento ni a fechaContable del feed.

Las líneas de la cartola no tienen IDs equivalentes a los del feed ni contraparte estructurada (RUT, banco y cuenta de origen). Conserva las repeticiones legítimas del archivo; importe y glosa no son una clave única.

Disponibilidad del detalle

En USD, cartolas.consultar_v2 entrega el número de cartola y los saldos de apertura y cierre. cartolas.detalle devuelve ese resumen, con lineas: null: todavía no ofrece sus operaciones individuales. Esto no significa que la cartola esté vacía.

En CLP, las líneas están disponibles cuando la sincronización las obtuvo. Si hay líneas pero el extracto no declaró número de cartola ni saldos de apertura y cierre, esos campos quedan en null, salvo que ya se hubieran obtenido en otra lectura. Los documentos se conservan como texto, incluidos sus ceros iniciales; también pueden venir vacíos o en ceros.

Antes de depender de los datos

Si el banco rechaza una consulta

Emisso lo informa como upstream_unexpected_response (502, sin reintento automático), con su motivo en el alcance. En movimientos lo intenta cuenta por cuenta, como se describe arriba. Usa el mismo código cuando la respuesta no tiene la forma esperada, trae una moneda no reconocida o es demasiado grande. bch_empresas.conexion.sincronizar pide siempre un mes calendario, y aun así el banco puede rechazar la consulta. Revisa el motivo y conserva el request_id para reportarlo.

La historia disponible debe comprobarse en el banco

Un mes antiguo puede llegar vacío sin que eso pruebe que no hubo movimientos: el banco no distingue un mes sin actividad de uno anterior a la cuenta. Si necesitas varios años de historia, comprueba en el portal del banco que estén disponibles.

Errores que vas a ver

CódigoQué significaQué hacer
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.
409 connection_sync_in_progressSolo por POST /v1/connections/{conn}/syncs: ese período ya tiene una sincronización en cola o corriendo. La tool conexion.sincronizar no lo devuelve: responde yaEnCurso: true.Sigue ese trabajo, o consulta directamente: puede que ya haya datos.
403 alcance_not_enabledLa conexión no tiene habilitado el alcance que la tool pide.Habilítalo en la conexión desde el dashboard, o quítalo del input de la sincronización.
409 connection_identity_mismatchLa empresa que ve el banco no coincide con la que declara la conexión: la clave no tiene acceso a esa empresa en el portal, o una fila sincronizada trajo el RUT de otra.Revisa que el «RUT de la empresa» sea el correcto y que esa clave pueda operarla en el portal. No reintentes sin revisar: reintentar no lo arregla.
502 upstream_unexpected_responseEl banco rechazó la consulta o devolvió una respuesta que Emisso no reconoce, como una moneda no soportada o una respuesta demasiado grande.Revisa el motivo y el detalle del alcance, y comprueba si la consulta funciona en el portal del banco. Si persiste, repórtalo junto con el request_id; no copies el payload crudo del banco.
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