Consultar movimientos de Banco Itaú

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "numeroCuenta": {
      "description": "Filtra por un número de cuenta. Omítelo para ver los movimientos de todas las cuentas de la conexión.",
      "type": "string"
    },
    "periodo": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}$",
      "description": "Un mes, en formato AAAA-MM y en calendario chileno (por ejemplo '2026-07'). Cada sitio de uso afina qué significa ahí: en una sincronización es el mes que se va a traer, y en una consulta a la caché es el filtro. Esta descripción base existe para que el campo nunca llegue pelado a quien lee el contrato."
    },
    "type": {
      "description": "Filtra por el eje del monto: 'credit' es plata que SALE y 'debit' plata que ENTRA, según el libro del banco. Omítelo para ver los dos.",
      "type": "string",
      "enum": [
        "credit",
        "debit"
      ]
    },
    "cursor": {
      "description": "Puntero opaco a la página siguiente. Reenvía tal cual el 'cursor' que devolvió la llamada anterior; nunca lo construyas a mano. Omítelo para pedir la primera página.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Cuántas filas trae la página, entre 1 y 500. Por omisión, 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "movimientos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "El identificador con el que Connect guardó esta fila. Itaú no publica un número de movimiento, así que Connect lo deriva del contenido de la fila (fecha, monto, glosa, documento y el saldo arrastrado). Úsalo para deduplicar en tu propio sistema; no es un folio del banco."
          },
          "numeroCuenta": {
            "type": "string",
            "description": "El número de la cuenta a la que pertenece el movimiento."
          },
          "periodo": {
            "type": "string",
            "description": "El mes (AAAA-MM) bajo el que está archivada la fila, derivado de la FECHA del movimiento y no del mes con que se pidió el sync. No entra en su identidad: pedirlo bajo otro período no separa el mismo movimiento en dos."
          },
          "fecha": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Fecha del movimiento, en formato AAAA-MM-DD. No trae hora: la cartola no la informa. null si el portal no trajo la celda."
          },
          "descripcion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La glosa del movimiento tal como aparece en la cartola (por ejemplo 'TRANSFERENCIA DE FONDOS')."
          },
          "documento": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El número de documento asociado al movimiento, cuando el portal lo trae. Itaú lo deja vacío (o en ceros) en cerca de una de cada cuatro filas: pagos masivos y cargos automáticos, por ejemplo. Ahí llega null, nunca '000000000'."
          },
          "monto": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible lo trae 'display'. Un null significa que el portal no trajo la celda, que no es lo mismo que cero."
          },
          "type": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "credit",
                  "debit"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Eje crédito/débito del LIBRO DEL BANCO, no el de la cartola: 'debit' es plata que ENTRA a la cuenta (un abono) y 'credit' es plata que SALE (un cargo). Es al revés de la lectura intuitiva y está así a propósito. El campo 'monto' es la magnitud SIN signo; el signo lo lleva 'display' ('credit' → negativo). 'null' significa que el banco no informó el tipo: no asumas ninguno de los dos."
          },
          "display": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El monto ya formateado a la chilena y CON signo, derivado de 'type' ('credit', plata que sale, se muestra negativo). Es una comodidad de presentación: se calcula en la lectura y no se persiste. Para operar con el número usa 'monto' (magnitud sin signo) junto con 'type'."
          },
          "saldo": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "El saldo que queda en la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo."
          },
          "oficina": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La sucursal que el portal asocia al movimiento, en su propio texto (por ejemplo 'OPERACIONES CENTRALES')."
          },
          "contraparte": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "rut": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El RUT de la contraparte, en formato '<cuerpo>-<DV>' sin puntos y con el DV en mayúscula. Es el mismo formato en que Connect lo guarda, así que sirve tal cual para cruzar contra documentos del SII."
                  },
                  "nombre": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El nombre o razón social de la contraparte, tal como lo publica el banco."
                  },
                  "banco": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El banco de la contraparte, en el texto del propio Itaú (por ejemplo 'BANCO DE CHILE / EDWARDS')."
                  }
                },
                "required": [
                  "rut",
                  "nombre",
                  "banco"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "Quién está al otro lado, cuando el movimiento es una transferencia y su documento calza con una TEF ya sincronizada. null significa que Connect no pudo resolverla: o el movimiento no es una transferencia, o el alcance 'transferencias' no está habilitado, o esa TEF cae fuera de los meses sincronizados. NUNCA significa que la transferencia no tuvo contraparte."
          },
          "superficie": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "ultimos_movimientos",
                  "movimientos_productos",
                  "saldos_y_movimientos",
                  "cartola_historica"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Por cuál pantalla del portal se leyó la fila. Es metadato de procedencia y no entra en la identidad del movimiento, así que el mismo movimiento visto por dos pantallas no se duplica. null en filas guardadas antes de que Connect registrara este dato."
          },
          "syncedAt": {
            "type": "string",
            "description": "Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la sincronización puede haber dejado de correr (por ejemplo, con la conexión pausada tras varios fallos) mientras esta tool sigue respondiendo con filas antiguas."
          }
        },
        "required": [
          "id",
          "numeroCuenta",
          "periodo",
          "fecha",
          "descripcion",
          "documento",
          "monto",
          "type",
          "display",
          "saldo",
          "oficina",
          "contraparte",
          "superficie",
          "syncedAt"
        ],
        "additionalProperties": false
      },
      "description": "Los movimientos guardados que calzan con los filtros, del más reciente al más antiguo. Una lista vacía significa que ese período no se ha sincronizado, no que no haya movimientos."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Puntero a la página siguiente. Si viene distinto de null hay más filas: vuelve a llamar reenviándolo tal cual en 'cursor'. Un null significa que no queda nada por traer."
    }
  },
  "required": [
    "movimientos",
    "cursor"
  ],
  "additionalProperties": false
}