# Sincronizar conexión Banco Itaú

> Sincroniza los alcances solicitados (saldos, movimientos) de Banco Itaú Empresas en una sola sincronización, incluida la cuenta dólar cuando la empresa tiene una.



{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}

|                     |                                                                    |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID**         | `itau_empresas.conexion.sincronizar`                               |
| **Nombre MCP**      | `itau_empresas__conexion__sincronizar`                             |
| **Conector**        | `itau_empresas`                                                    |
| **Plano**           | `read`                                                             |
| **Alcances**        | `saldos`, `movimientos`, `transferencias`                          |
| **Scope (permiso)** | `itau_empresas:read`                                               |
| **Auth**            | `connection_credentials`                                           |
| **Versión**         | `1`                                                                |
| **Sensible**        | sí                                                                 |
| **Deprecado**       | no                                                                 |
| **Comportamiento**  | readOnly=false, destructive=false, idempotent=true, openWorld=true |

> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST y campo `connectionId` en el `execute_write` de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](/docs/referencia/conexiones/estado-consultar).

## Qué hace [#qué-hace]

'saldos' es una foto del momento, no del período: sólo se sincroniza cuando se pide el período corriente. Los movimientos salen de la pantalla de cada cuenta, que publica sus últimos 100 movimientos (en una cuenta con mucho movimiento son pocos días): el período pedido etiqueta la corrida, pero cada movimiento queda archivado bajo el mes de SU fecha. La cuenta dólar suma además su última cartola mensual cerrada.

## Entrada [#entrada]

| Campo      | Tipo                                                       | Requerido | Descripción                                                                                                                                                                                                                                                                                         |
| ---------- | ---------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `periodo`  | string `^\d{4}-\d{2}$`                                     | sí        | El mes que se va a sincronizar, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Traer varios meses son varias llamadas, una por mes. El mismo mes de una conexión se puede pedir una vez cada 10 minutos; antes responde 'rate\_limited'.                                       |
| `alcances` | lista de `"saldos"` · `"movimientos"` · `"transferencias"` | sí        | Qué módulos de datos traer en esta corrida, al menos uno. Todos se traen en la misma sincronización, así que pedir varios en una llamada cuesta menos que llamar una vez por cada uno. Un alcance debe estar habilitado en la conexión; si no lo está, la llamada responde 'alcance\_not\_enabled'. |

<details>
  <summary>
    JSON Schema de entrada
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "periodo": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}$",
        "description": "El mes que se va a sincronizar, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Traer varios meses son varias llamadas, una por mes. El mismo mes de una conexión se puede pedir una vez cada 10 minutos; antes responde 'rate_limited'."
      },
      "alcances": {
        "minItems": 1,
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "saldos",
            "movimientos",
            "transferencias"
          ]
        },
        "description": "Qué módulos de datos traer en esta corrida, al menos uno. Todos se traen en la misma sincronización, así que pedir varios en una llamada cuesta menos que llamar una vez por cada uno. Un alcance debe estar habilitado en la conexión; si no lo está, la llamada responde 'alcance_not_enabled'."
      }
    },
    "required": [
      "periodo",
      "alcances"
    ]
  }
  ```
</details>

## Ejemplo [#ejemplo]

```bash title="curl"
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"]}}'
```

```json title="MCP · meta-tool execute_write"
{
  "tool": "itau_empresas.conexion.sincronizar",
  "params": {
    "periodo": "2026-09",
    "alcances": [
      "saldos",
      "movimientos"
    ]
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}
```

**Salida esperada (200):**

```json
{
  "data": {
    "periodo": "2026-09",
    "estado": "encolado",
    "jobId": "sjb_7k2m4n6p8q1r3s5t7u9v1",
    "yaEnCurso": false
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "itau_empresas.conexion.sincronizar",
    "plane": "read",
    "latency_ms": 58240,
    "audit_status": "recorded"
  }
}
```

> Cada sincronización de Itaú tarda cerca de un minuto, también la segunda y las siguientes. Dentro de una misma llamada, todos los alcances que pidas comparten esa entrada, así que pedir 'saldos' y 'movimientos' juntos cuesta lo mismo que pedir uno solo.

## Salida [#salida]

| Campo                          | Tipo                              | Requerido | Descripción                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------ | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `periodo`                      | string                            | sí        | Eco del período que se pidió, para poder correlacionar la respuesta sin guardarlo tú.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `estado`                       | `"encolado"` · `"completado"`     | sí        | 'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync consulta el sistema externo y puede tardar minutos, así que no se te hace esperar por él.                                                                                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `jobId`                        | string                            | null      | no                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/\{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.succeeded' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado', porque ahí el resultado ya está en la respuesta, y cuando 'yaEnCurso' es true y esa sincronización ya está corriendo. |
| `yaEnCurso`                    | booleano                          | no        | 'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período. |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results`                      | lista de objeto                   | no        | El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada.                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].alcance`            | string                            | sí        | Cuál de los alcances pedidos describe esta fila. Hay una fila por alcance solicitado, en el orden canónico del conector, no en el orden en que los pediste.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].marcador`           | string                            | no        | Uso interno de Emisso; no se publica. En GET /v1/syncs/\{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].status`             | `"ok"` · `"partial"` · `"failed"` | sí        | 'ok' = el alcance terminó bien; que 'recordsSynced' sea 0 no lo vuelve un fallo. 'partial' = se guardó lo que se pudo leer, pero una parte del alcance quedó sin leer, y 'detalle' dice cuál: lo sincronizado sirve, y una próxima sincronización puede completar lo que falta. 'failed' = no terminó bien, y la causa va en 'error'; mira igual 'recordsSynced', porque un 'failed' no garantiza que no se haya escrito nada. Y revisa fila por fila: un alcance puede fallar mientras los otros de la misma corrida terminan bien.                                                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].recordsSynced`      | entero                            | sí        | Cuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'.                                                                                                                                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].error`              | string                            | no        | Por qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos\_truncated', 'cartolas\_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre.                                                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].cuentasConsultadas` | entero                            | no        | Cuántas cuentas se alcanzaron a consultar. Es lo que vuelve interpretable un 'recordsSynced: 0': cero con una cuenta consultada significa que el portal no publicó nada en su ventana, y cero con cero cuentas significa que ni siquiera se llegó a preguntar. Los dos casos traen el mismo 0, así que revisa este campo antes de reportar «no hay datos».                                                                                                                                                                                                                                                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `results[].detalle`            | string                            | no        | Explicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo.                                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

<details>
  <summary>
    JSON Schema de salida
  </summary>

  ```json
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "periodo": {
        "type": "string",
        "description": "Eco del período que se pidió, para poder correlacionar la respuesta sin guardarlo tú."
      },
      "estado": {
        "type": "string",
        "enum": [
          "encolado",
          "completado"
        ],
        "description": "'encolado' = la sincronización quedó en cola y va a empezar enseguida; esta respuesta NO trae datos todavía, y el trabajo se sigue por 'jobId'. 'completado' = la sincronización ya corrió y su resumen por alcance viene en 'results'. Un cliente recibe siempre 'encolado': un sync consulta el sistema externo y puede tardar minutos, así que no se te hace esperar por él."
      },
      "jobId": {
        "description": "El identificador de la sincronización encolada. Por la API REST, el avance se consulta en 'GET /v1/syncs/{jobId}'; por MCP, búscalo en 'trabajos' de 'conexiones.estado.consultar' y revisa 'datosListos' ahí mismo. Es el mismo id que viaja en el webhook 'sync.succeeded' o 'sync.failed' si tu plan los incluye. Es null cuando 'estado' es 'completado', porque ahí el resultado ya está en la respuesta, y cuando 'yaEnCurso' es true y esa sincronización ya está corriendo.",
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ]
      },
      "yaEnCurso": {
        "description": "'true' significa que ya había una sincronización viva para esa conexión y ese período, así que no se creó otra. No es un error ni un rechazo. Si esa sincronización sigue en cola, 'jobId' es el suyo; si ya está corriendo, 'jobId' llega null y su avance se ve en 'trabajos' de 'conexiones.estado.consultar'. Cubre el período, no necesariamente los alcances que pediste: si pediste otros, vuelve a pedirlos cuando termine. Ojo con el otro lado: 'false' NO garantiza que la hayas creado tú: dos llamadas a la vez pueden recibir las dos 'false' y el MISMO 'jobId'. Lo que sí vale siempre es que hay una sola sincronización activa por conexión y período.",
        "type": "boolean"
      },
      "results": {
        "description": "El resumen por alcance, una fila por alcance sincronizado. AUSENTE cuando 'estado' es 'encolado': el trabajo todavía no corrió. Ausente no es lo mismo que vacío: un arreglo vacío significaría que se miró y no había nada.",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "alcance": {
              "type": "string",
              "description": "Cuál de los alcances pedidos describe esta fila. Hay una fila por alcance solicitado, en el orden canónico del conector, no en el orden en que los pediste."
            },
            "marcador": {
              "description": "Uso interno de Emisso; no se publica. En GET /v1/syncs/{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores.",
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "ok",
                "partial",
                "failed"
              ],
              "description": "'ok' = el alcance terminó bien; que 'recordsSynced' sea 0 no lo vuelve un fallo. 'partial' = se guardó lo que se pudo leer, pero una parte del alcance quedó sin leer, y 'detalle' dice cuál: lo sincronizado sirve, y una próxima sincronización puede completar lo que falta. 'failed' = no terminó bien, y la causa va en 'error'; mira igual 'recordsSynced', porque un 'failed' no garantiza que no se haya escrito nada. Y revisa fila por fila: un alcance puede fallar mientras los otros de la misma corrida terminan bien."
            },
            "recordsSynced": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Cuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'."
            },
            "error": {
              "description": "Por qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos_truncated', 'cartolas_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre.",
              "type": "string"
            },
            "cuentasConsultadas": {
              "description": "Cuántas cuentas se alcanzaron a consultar. Es lo que vuelve interpretable un 'recordsSynced: 0': cero con una cuenta consultada significa que el portal no publicó nada en su ventana, y cero con cero cuentas significa que ni siquiera se llegó a preguntar. Los dos casos traen el mismo 0, así que revisa este campo antes de reportar «no hay datos».",
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "detalle": {
              "description": "Explicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo.",
              "type": "string"
            }
          },
          "required": [
            "alcance",
            "status",
            "recordsSynced"
          ],
          "additionalProperties": false
        }
      }
    },
    "required": [
      "periodo",
      "estado"
    ],
    "additionalProperties": false
  }
  ```
</details>

## Errores de esta tool [#errores-de-esta-tool]

| Código                 | HTTP | Reintentable | Qué hacer                                                                                                           |
| ---------------------- | ---- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled`  | 403  | no           | Reactívala en /connections o usa otra conexión del mismo sistema.                                                   |
| `connection_not_found` | 404  | no           | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
| `alcance_not_enabled`  | 403  | no           | Habilita el alcance en /connections o quítalo del input de la sincronización.                                       |
| `too_many_pending`     | 429  | sí           | Deja terminar los trabajos en curso antes de encolar más.                                                           |

La llamada solo encola: las fallas del sistema externo (credencial, sesión, caída del portal) no llegan en esta respuesta, sino en el trabajo: en `outcomes` y `last_error` de `GET /v1/syncs/{jobId}`, o en los webhooks `sync.succeeded` (un alcance que falló junto a otros que terminaron) y `sync.failed`.

Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](/docs/referencia/errores).

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

* [`itau_empresas.movimientos.consultar`](/docs/referencia/itau_empresas/movimientos-consultar): lee el alcance `movimientos` que esta sincronización escribe.
* [`itau_empresas.transferencias.consultar`](/docs/referencia/itau_empresas/transferencias-consultar): lee el alcance `transferencias` que esta sincronización escribe.
* [`itau_empresas.saldos.consultar`](/docs/referencia/itau_empresas/saldos-consultar): lee el alcance `saldos` que esta sincronización escribe.


---

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/referencia/itau_empresas/conexion-sincronizar.
