Banco Itaú Empresas

Con la clave del Portal Empresas, itau_empresas sincroniza saldos, movimientos y transferencias de Banco Itaú hacia el plano persistido de Connect, 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).

Itaú tiene la misma particularidad que BICE y Santander: su portal protege el acceso con un desafío de navegador. Connect lo resuelve por ti, con las reglas que se explican abajo.

Qué necesitas para conectar

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

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

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

{
  "data": {
    "periodo": "2026-09",
    "results": [
      { "alcance": "saldos", "status": "ok", "recordsSynced": 1, "cuentasConsultadas": 1 },
      { "alcance": "movimientos", "status": "ok", "recordsSynced": 8, "cuentasConsultadas": 1 }
    ]
  },
  "meta": { "request_id": "req_...", "tool_id": "itau_empresas.conexion.sincronizar", "plane": "read" }
}

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 devuelve cero con su explicación en detalle. Y el login no exige esperarlo en línea: el trabajo se encola por la API de control.

Verdades operativas

La ventana del portal es de unas seis semanas

Esta es la diferencia que más conviene tener clara antes de integrar. La pantalla de la que Connect lee los movimientos publica alrededor de seis semanas hacia atrás, y el portal no acepta 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 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 Connect trae los tres últimos meses; pedir uno más antiguo es sincronizar con ese período.

La contraparte vive en transferencias, no en la cartola

La cartola de Itaú no publica con quién fue la operación: son siete columnas y ninguna es el otro lado. La glosa a veces embebe un RUT, pero sólo en cerca de una de cada seis filas y truncada a 28 caracteres, así que no sirve para conciliar.

Las pantallas de transferencias sí lo publican, y completo: RUT, nombre y banco en el 100 % de sus filas. Por eso transferencias es un alcance aparte y no una columna más de movimientos:

• Cubre más atrás. La cartola llega seis semanas; las transferencias, un mes por cada período que sincronices. En lo medido, dos de cada tres transferencias eran anteriores a la ventana de la cartola.
• Incluye las que fallaron. Una transferencia con estado: "error" existe, no produjo movimiento y no aparece en ninguna cartola.
• Su identificador lo da el banco. El id de una transferencia es el número de TEF que acuña Itaú, a diferencia de un movimiento, que Connect identifica por su contenido.

Y las dos se cruzan. Cuando un movimiento es una transferencia, su documento es ese mismo número de TEF, así que movimientos.consultar te devuelve la contraparte ya resuelta en el campo contraparte. No tienes que cruzar nada a mano:

{
  "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" }
}

Un contraparte: null significa que Connect no pudo resolverla (el movimiento no es una transferencia, o el alcance transferencias no está habilitado, o esa TEF cae fuera de los meses sincronizados), nunca que la operación no tuvo contraparte.

Para conciliar contra tus documentos del SII, el camino es transferencias.consultar con el filtro contraparteRut: acepta el RUT en cualquier formato y Connect lo canoniza antes de buscar.

El portal exige un navegador para entrar

El acceso a Itaú corre detrás de una protección anti-bot que no se puede atravesar con HTTP puro. Cuando conexion.sincronizar necesita entrar, abre un navegador remoto solo para ese login; desde ahí, todos los datos viajan por HTTP normal, igual que en los demás bancos.

A diferencia de BICE y Santander, Itaú no cachea la sesión: cada sincronización acuña su propio navegador. Eso hace que toda corrida cueste cerca de un minuto, también la segunda y las siguientes. A cambio, no hay sesión que expire a mitad de camino ni estado compartido entre corridas. Dentro de una misma llamada, todos los alcances que pidas comparten ese único login, así que 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 abrir ese navegador. Cualquier otra tool que necesite sesión de portal responde 409 connection_session_pending, en vez de dejarte esperando un login largo. 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: sin sesión cacheada no hay nada barato que verificar, así que responde connection_session_pending. La forma de saber si una credencial sirve es sincronizar.

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

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

Próximos pasos

• Las cinco tools, con contrato completo: referencia de itau_empresas.
• La separación entre escribir la caché y leerla: Sincronizar y consultar.
• Saber de cada sync sin preguntar: Webhooks.