# 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](/docs/sistemas/itau-corporate).

## Qué necesitas para conectar [#qué-necesitas-para-conectar]

En el [enlace de conexión](/docs/empezar/conectar) la persona entrega la **clave del Portal Empresas**, en tres campos:

| Campo             | Qué es                                               |
| ----------------- | ---------------------------------------------------- |
| RUT de acceso     | El RUT de la persona que inicia sesión en el portal. |
| Clave             | Su clave del Portal Empresas de Itaú.                |
| 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`         | Las 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](/docs/conceptos/sincronizar-consultar#leer-el-saldo-de-una-cuenta)) | `itau_empresas.saldos.consultar`         |
| `movimientos`    | Los movimientos de las cuentas corrientes y de la cuenta dólar, con glosa, documento, sucursal y saldo arrastrado                                                                                                                             | `itau_empresas.movimientos.consultar`    |
| `transferencias` | Las TEF enviadas y recibidas, con **RUT, nombre y banco de la contraparte**                                                                                                                                                                   | `itau_empresas.transferencias.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/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):

```json
{
  "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](/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, "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 [#antes-de-depender-de-los-datos]

### Itaú entrega los últimos 100 movimientos de cada cuenta corriente [#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-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 [#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 [#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:

```json
{
  "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-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 [#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 [#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 [#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 [#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 [#errores-que-vas-a-ver]

| Código                               | Qué significa                                                                      | Qué hacer                                                                                         |
| ------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `409 connection_session_pending`     | El 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_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. La sincronización programada lo reintenta sola.                              |

El envelope de cada código está en el [catálogo de errores](/docs/operar/errores).

## Próximos pasos [#próximos-pasos]

* Las cinco tools, con contrato completo: [referencia de `itau_empresas`](/docs/referencia/itau_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/itau-empresas.
