Sistemas

Banco Itaú Empresas

Saldos, movimientos y transferencias de Banco Itaú Empresas, incluida la cuenta dólar, con RUT, nombre y banco de la contraparte.

Con la clave del Portal Empresas, itau_empresas sincroniza saldos, movimientos y transferencias de Banco Itaú, incluida la cuenta dólar cuando la empresa tiene una, hacia el plano persistido de Emisso, y tres tools de consulta los leen de ahí 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).

Cada sincronización de Itaú tarda cerca de un minuto; abajo se explica qué esperar.

Si al ingresar al banco ves «Inicia sesión desde Corporate», elige Itaú Corporate.

Qué necesitas para conectar

En el enlace de conexión la persona entrega la clave del Portal Empresas, en tres campos:

CampoQué es
RUT de accesoEl RUT de la persona que inicia sesión en el portal.
ClaveSu clave del Portal Empresas de Itaú.
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
saldosLas cuatro cifras de la ficha de cada cuenta: total, retenciones, disponible y disponible con línea de crédito, como una foto por día (cómo leer el saldo de una cuenta)itau_empresas.saldos.consultar
movimientosLos movimientos de las cuentas corrientes y de la cuenta dólar, con glosa, documento, sucursal y saldo arrastradoitau_empresas.movimientos.consultar
transferenciasLas TEF enviadas y recibidas, con RUT, nombre y banco de la contraparteitau_empresas.transferencias.consultar

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

Sincronizar

curl -X POST https://connect.emisso.ai/api/v1/tools/itau_empresas.conexion.sincronizar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"periodo":"2026-09","alcances":["saldos","movimientos"]}}'

Respuesta de encolado (200, metadatos recortados):

{
  "data": {
    "periodo": "2026-09",
    "estado": "encolado",
    "jobId": "sjb_9f2kc0q8w1m4x7t3p6b5d",
    "yaEnCurso": false
  },
  "meta": {
    "request_id": "req_...",
    "tool_id": "itau_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, "cuentasConsultadas": 1 },
  { "alcance": "movimientos", "status": "ok", "recordsSynced": 8, "cuentasConsultadas": 1 }
]

cuentasConsultadas acompaña a los dos alcances 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.

Antes de depender de los datos

Itaú entrega los últimos 100 movimientos de cada cuenta corriente

Esta es la diferencia que más conviene tener clara antes de integrar. Itaú entrega los últimos 100 movimientos de cada cuenta corriente, no un rango de días: en una cuenta con mucho movimiento son pocos días, y en una tranquila pueden ser meses. Además, Itaú no permite pedir un rango de fechas: el periodo que mandas etiqueta la corrida, no filtra al banco. En consecuencia:

  • Cada movimiento queda archivado bajo el mes de su propia fecha, no bajo el período con que pediste el sync. Una corrida de septiembre deja filas de septiembre y de agosto, cada una en su mes.
  • La cartola de la cuenta corriente no tiene carga histórica. Los meses anteriores a la conexión no están y no se pueden traer: el historial de movimientos empieza a construirse el día que conectas. Si necesitas cobertura desde una fecha, conecta antes de esa fecha.
  • transferencias sí la tiene. Esas dos pantallas se piden por mes, así que el alcance honra el periodo de verdad. Al crear la conexión Emisso trae los tres últimos meses; pedir uno más antiguo es sincronizar con ese período.

La cuenta dólar trae su última cartola mensual cerrada

La cuenta dólar no se rige por los 100 movimientos. Cada sincronización trae dos partes:

  • La última cartola mensual cerrada, completa. Al conectar, ese mes llega entero, aunque sea anterior a la conexión.
  • Los movimientos posteriores a esa cartola, los del mes en curso que el banco todavía no cierra.

Las cartolas anteriores a la última no se traen: el historial más antiguo se arma mes a mes desde que conectas, igual que en la cuenta corriente. Un movimiento que aparece en las dos partes se guarda una sola vez.

Los movimientos de la cuenta dólar llegan con moneda: "USD", y monto, saldo y display están en dólares. Filtra o agrupa por moneda antes de sumar: un total que mezcla pesos y dólares no significa nada. Si la empresa tiene más de una cuenta dólar, hoy se lee una.

El id de un movimiento puede cambiar

Itaú no publica un número de movimiento, así que Emisso identifica cada fila por su contenido, incluido el saldo que deja. El banco reescribe ese contenido más seguido de lo que parece:

  • Recalcula los saldos cuando registra un movimiento con fecha anterior. Todos los movimientos siguientes de ese día pasan a tener otro saldo.
  • Corrige glosas y documentos al cierre del día, cuando un movimiento provisorio pasa a definitivo.

En los dos casos, el movimiento aparece en movimientos.consultar con un id nuevo y la fila anterior deja de aparecer: Emisso deja guardado lo mismo que muestra el banco. Si cargas los movimientos en tu sistema, no deduplices sólo por id: combínalo con numeroCuenta, fecha, monto, type y documento. Por lo mismo, no ordenes la cartola encadenando saldos: el orden de un día puede cambiar después.

Cómo se resuelve la contraparte

movimientos.consultar resuelve contraparte al leer los datos guardados, con este orden:

  1. TEF sincronizada. Busca la transferencia cuyo número coincide con el documento del movimiento. Si la encuentra, conserva sus datos intactos, aunque rut sea null o todos los campos de contraparte sean null.
  2. RUT en la glosa de un abono, solo si no hay TEF. Para type: "debit", una glosa que empieza por Transf. de, sin distinguir mayúsculas, puede aportar un RUT completo de 7 u 8 dígitos más su dígito verificador. Se comprueban el formato y el DV; un RUT incompleto o inválido no se extrae. En este caso solo se completa rut: nombre y banco quedan en null.

La extracción descarta ceros iniciales, delimitación ambigua, otra referencia que pueda ser un segundo RUT y señales acotadas de contradicción, como una transferencia rechazada o anulada. No reconoce todos los formatos posibles de glosa.

La validación del RUT no acredita identidad ni titularidad. Tampoco deduzcas la fuente por los campos nulos: una TEF puede tenerlos vacíos. Esta lectura no crea transferencias ni modifica la glosa guardada.

Por ejemplo, una TEF encontrada puede aportar:

{
  "fecha": "2026-09-17",
  "descripcion": "TRANSFERENCIA DE FONDOS",
  "documento": "900100011",
  "monto": 213333,
  "type": "credit",
  "contraparte": { "rut": "76123456-0", "nombre": "COMERCIAL RIBERA LTDA", "banco": "BANCO DEMO" }
}

contraparte: null significa que Emisso no pudo resolverla, nunca que la operación no tuvo contraparte. Una TEF encontrada con todos sus campos nulos conserva su objeto; no se reemplaza por datos de la glosa.

El alcance transferencias sigue aportando información distinta de los movimientos:

  • Consulta por mes. Sus pantallas respetan el período solicitado, mientras la lectura de movimientos conserva la ventana que publica el portal.
  • Incluye las transferencias fallidas. Una fila con estado: "error" puede existir sin haber producido un movimiento.
  • Conserva el número de TEF del banco y los datos de contraparte disponibles en ese detalle, incluidos nombre y banco.

El filtro contraparteRut de transferencias.consultar busca entre las TEF sincronizadas: acepta distintas presentaciones del RUT y lo canoniza antes de buscar. No incluye los RUT extraídos de glosas por movimientos.consultar.

Cada sincronización tarda cerca de un minuto

Cada conexion.sincronizar entra al banco desde cero, así que tarda cerca de un minuto, también la segunda y las siguientes. Todos los alcances de una misma llamada comparten esa entrada: pedir saldos y movimientos juntos cuesta lo mismo que pedir uno solo.

connection_session_pending: qué es y qué hacer

Solo la sincronización puede entrar a Itaú. Cualquier otra tool que necesite ese acceso responde 409 connection_session_pending, en vez de dejarte esperando. El código es reintentable: ejecuta itau_empresas.conexion.sincronizar o espera la sincronización programada.

Por lo mismo, conexion.verificar no comprueba la clave contra el banco y responde connection_session_pending. La forma de saber si una credencial sirve es sincronizar.

connection_session_pending solo dice que todavía no hay una sincronización que haya entrado al banco. Si la que falla es la sincronización misma, por ejemplo porque el banco rechazó la entrada, repetirla no lo arregla: revisa el estado de la conexión en el panel y, si sigue fallando con una clave que funciona en el portal de Itaú, escríbenos por el chat.

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 (credit) o entra (debit) según el libro del banco (al revés de como se lee una cartola), 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 signo que escribe el portal en la celda es ruido de la pantalla y no del dato: la misma transacción sale -$ 140.424 en una pantalla y $ 140.424 en otra. Quien manda es la columna, y eso es lo que Emisso guarda.

El documento falta en cerca de una de cada cuatro filas

Itaú deja documento vacío, o en ceros, en pagos masivos, cargos automáticos y otros movimientos sin papeleta. Ahí el campo llega en null, nunca como "000000000": tratarlos como documento cero haría que todos esos movimientos compartieran identificador.

El período se pide, no entra 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

CódigoQué significaQué hacer
409 connection_session_pendingEl acceso a Itaú 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. La sincronización programada lo reintenta sola.

El envelope de cada código está en el catálogo de errores.

Próximos pasos

En esta página