Consultar movimientos de BICE Empresas

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "description": "Filtra por el mes (AAAA-MM) con el que se sincronizó la fila. Como la cartola de BICE corre de fin de mes a fin de mes, un período puede traer movimientos fechados en los últimos días del mes anterior. Sin él, la respuesta cruza todos los períodos guardados.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}$"
    },
    "numeroCuenta": {
      "description": "Filtra por una sola cuenta, escrita igual que el 'numeroCuenta' de las filas. Sin él vienen todas las cuentas de la conexión.",
      "type": "string"
    },
    "type": {
      "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.",
      "type": "string",
      "enum": [
        "credit",
        "debit"
      ]
    },
    "cursor": {
      "description": "Para pedir la página siguiente: el valor que la respuesta anterior devolvió en 'cursor', tal cual. Nunca lo construyas ni lo edites a mano. Omítelo para empezar por la primera página.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Cuántas filas trae una página, entre 1 y 500. Por defecto, 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": "La identidad estable del movimiento: la huella con la que se guardó. El mismo movimiento llega por dos rutas del banco con formatos distintos y por las dos trae este mismo 'id', así que sirve para deduplicar el día que comparten dos cartolas sin comparar campos de presentación."
          },
          "numeroCuenta": {
            "type": "string",
            "description": "El identificador ESTABLE de la cuenta a la que pertenece esta fila. No es la máscara que muestra el portal en pantalla, que cambia en cada sesión: es el mismo valor en saldos y movimientos, y el que espera el filtro 'numeroCuenta'."
          },
          "currency": {
            "type": "string",
            "description": "La moneda de la cuenta, en código de tres letras (por ejemplo 'CLP'). BICE la manda a veces como código numérico y aquí ya viene traducida a las tres letras."
          },
          "periodo": {
            "type": "string",
            "description": "El mes (AAAA-MM) con el que se sincronizó esta fila. Es la ventana con que se pidió, no una propiedad del movimiento: la cartola de BICE corre de fin de mes a fin de mes, así que el período '2026-07' incluye movimientos fechados el 30 de junio. La fecha vive en 'fecha'."
          },
          "fecha": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "La fecha del movimiento (ISO 8601), tal como la entrega el banco. Puede caer en el mes anterior al de 'periodo', porque la cartola de BICE corre de fin de mes a fin de mes. 'null' cuando el banco no la trajo en una forma reconocible."
          },
          "monto": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "La magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible, 'display'. 'null' cuando ni el débito ni el crédito traen un valor distinto de cero: el banco manda las dos celdas siempre y escribe 0 en la que no aplica, así que ese 0 no es un movimiento de 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'."
          },
          "saldoContable": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "El saldo de la cuenta después de este movimiento. Es un balance: no lleva 'type' y conserva su propio signo, así que un sobregiro es negativo."
          },
          "descripcion": {
            "type": "string",
            "description": "La glosa del movimiento, tal como la escribe el banco. Cadena vacía cuando el banco no la trae."
          },
          "documento": {
            "type": "string",
            "description": "El número de documento del movimiento, tal como lo entrega el banco. Ojo al compararlo: una ruta del banco lo manda con nueve dígitos y la otra truncado a los últimos ocho, así que dos textos distintos pueden ser el mismo documento. Para saber si dos filas son el mismo movimiento usa 'id'. Cadena vacía cuando el banco no lo trae."
          },
          "counterparty": {
            "type": "object",
            "properties": {
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "El nombre o razón social de la contraparte, tal como lo escribe el banco (MAYÚSCULAS y sin tildes en muchas filas: es el texto del portal, no un dato normalizado). 'null' cuando la glosa no lo trae."
              },
              "rut": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "El RUT de la contraparte, sin puntos y con guión (por ejemplo '76123456-0'): el banco lo escribe con puntos dentro de la glosa y aquí ya viene canonizado, en la MISMA forma con que el SII identifica a sus contrapartes, para que las dos fuentes crucen. No se valida el dígito verificador; si llegó en una forma que no se reconoce, viaja tal cual y nunca convertido a la fuerza. 'null' cuando la glosa no lo trae."
              },
              "bank": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "El banco de LA CONTRAPARTE, no el tuyo. Ojo con el formato, que depende de la dirección: en un cargo el banco lo escribe abreviado y TRUNCADO a diez caracteres ('B.Santande', 'B.Scotiaba', 'B.Chile'), y en un abono lo escribe corrido ('Security', 'BCI'). Viaja tal como lo manda el banco, sin completar lo truncado: adivinar el resto sería inventar. 'null' cuando la glosa no lo trae."
              },
              "account": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "El número de cuenta de la contraparte, tal como lo escribe el banco dentro de la glosa, que es el único lugar donde la manda: su respuesta no trae ningún campo de contraparte aparte. Solo la traen los cargos: un abono nombra a quién y desde qué institución, nunca la cuenta de origen. 'null' en todo abono y cuando la glosa no lo trae."
              }
            },
            "required": [
              "name",
              "rut",
              "bank",
              "account"
            ],
            "additionalProperties": false,
            "description": "La contraparte del movimiento, extraída de la glosa que escribe el banco. QUÉ LADO ES depende de 'type': en un abono ('debit', plata que entra) es el origen; en un cargo ('credit', plata que sale) es el destinatario. Los cuatro campos vienen en 'null' cuando el banco no informó contraparte, que es lo normal en pagos de tarjeta, comisiones y cargos de impuestos. Revisa 'counterpartySource' antes de concluir que falta un dato. Son datos personales de terceros: trátalos como tales."
          },
          "counterpartySource": {
            "anyOf": [
              {
                "type": "string",
                "const": "descripcion"
              },
              {
                "type": "null"
              }
            ],
            "description": "De dónde salió 'counterparty', para no tener que adivinarlo. 'descripcion': lo extrajimos de la glosa, que en BICE es el único lugar donde viaja la contraparte, porque el banco no adjunta un detalle estructurado como sí hacen otros. 'null': EL BANCO NO INFORMÓ CONTRAPARTE en esta fila, que es lo normal en pagos de la tarjeta propia, comisiones, cargos automáticos y pagos de impuestos; no es un dato que falte por un problema de Connect. El texto completo sigue en 'descripcion'."
          }
        },
        "required": [
          "id",
          "numeroCuenta",
          "currency",
          "periodo",
          "fecha",
          "monto",
          "type",
          "display",
          "saldoContable",
          "descripcion",
          "documento",
          "counterparty",
          "counterpartySource"
        ],
        "additionalProperties": false
      },
      "description": "Los movimientos guardados, del más reciente al más antiguo. Una lista vacía significa que ese período todavía no se sincronizó, no que no haya movimientos."
    },
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "El cursor de la página siguiente. Distinto de null significa que quedan más filas: reenvíalo tal cual en 'cursor'. 'null' significa que esta es la última página."
    }
  },
  "required": [
    "movimientos",
    "cursor"
  ],
  "additionalProperties": false
}