Consultar movimientos de BancoEstado

{
  "$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."
    },
    "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": {
          "numeroCuenta": {
            "type": "string",
            "description": "El número de la cuenta a la que pertenece el movimiento."
          },
          "periodo": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El mes (AAAA-MM) con el que se sincronizó esta fila. Es cómo se pidió el dato, no una propiedad del movimiento: no entra en su identidad, así que volver a traerlo bajo otro período no crea una fila nueva ni infla los totales."
          },
          "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 banco no trajo la celda."
          },
          "descripcion": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La glosa del movimiento tal como aparece en la cartola (por ejemplo 'PAGO PROVEEDOR')."
          },
          "documento": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "El número de documento asociado al movimiento, cuando el banco lo trae."
          },
          "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 banco 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 oficina que el banco asocia al movimiento, en su propio texto (por ejemplo 'STGO.PRINCIPAL')."
          },
          "origen": {
            "type": "string",
            "enum": [
              "linea",
              "historica"
            ],
            "description": "Por cuál de las dos cartolas del banco se trajo la fila: 'linea' es la del mes en curso e 'historica' la de los meses ya cerrados. Es metadato de procedencia y no entra en la identidad del movimiento, así que el mismo movimiento traído por las dos no se duplica."
          },
          "syncedAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cuándo se leyó esta fila del banco (ISO 8601). Si está vieja, la caché puede haber dejado de moverse (por ejemplo, con la conexión pausada tras varios fallos de credencial) mientras esta tool sigue respondiendo con filas antiguas."
          }
        },
        "required": [
          "numeroCuenta",
          "periodo",
          "fecha",
          "descripcion",
          "documento",
          "monto",
          "type",
          "display",
          "saldo",
          "oficina",
          "origen",
          "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
}