Buscar una transferencia en BCI (beta)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "monto": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "El monto del pago, sin signo, en la moneda de 'moneda'. Se compara exacto, al peso."
    },
    "fecha": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "x-emisso-formato": "AAAA-MM-DD",
      "description": "El día (AAAA-MM-DD) en que se hizo la transferencia, según quien pagó."
    },
    "rutContraparte": {
      "description": "El RUT de quien pagó (o de quien recibió, con sentido 'enviada'), en cualquier formato: '76.123.456-0' o '76123456-0'. Sin él, la confianza máxima es 'media'.",
      "type": "string"
    },
    "sentido": {
      "default": "recibida",
      "description": "'recibida' busca plata que entró a la cuenta; 'enviada', plata que salió. Por defecto, 'recibida'.",
      "type": "string",
      "enum": [
        "recibida",
        "enviada"
      ]
    },
    "toleranciaDias": {
      "default": 1,
      "description": "Cuántos días antes y después de 'fecha' se buscan movimientos, entre 0 y 7. Por defecto, 1: cubre un pago hecho de noche o un fin de semana que el banco registra al día siguiente.",
      "type": "integer",
      "minimum": 0,
      "maximum": 7
    },
    "moneda": {
      "default": "CLP",
      "description": "La moneda de la cuenta donde buscar, en código de tres letras. Por defecto, 'CLP'.",
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "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"
    }
  },
  "required": [
    "monto",
    "fecha"
  ]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "candidatas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "confianza": {
            "type": "string",
            "enum": [
              "alta",
              "media",
              "baja"
            ],
            "description": "'alta': el RUT y el monto coinciden. 'media': el monto coincide y no hay RUT con qué comparar (no lo pediste o el banco no lo trajo en el detalle). 'baja': el monto coincide pero pagó otro RUT, o pagó el mismo RUT por otro monto."
          },
          "motivos": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "rut_coincide",
                "rut_distinto",
                "rut_no_informado",
                "monto_coincide",
                "monto_distinto",
                "fecha_exacta",
                "fecha_cercana"
              ]
            },
            "description": "Qué coincidió y qué no, para explicar la confianza. 'fecha_cercana' = dentro de la tolerancia, otro día."
          },
          "diferenciaDias": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Días entre la fecha del movimiento y la pedida. Negativo si el movimiento es anterior."
          },
          "movimiento": {
            "type": "object",
            "properties": {
              "numeroCuenta": {
                "type": "string",
                "description": "El número de la cuenta a la que pertenece esta fila, tal como lo entrega el portal de BCI. Es el mismo valor en saldos y movimientos, y el que espera el filtro 'numeroCuenta'."
              },
              "currency": {
                "type": "string",
                "description": "La moneda de la cuenta a la que pertenece este movimiento, en código de tres letras ('CLP', 'USD'). Sale de la cuenta, no del movimiento. NUNCA sumes montos de monedas distintas: una misma conexión puede tener cuentas en pesos y en dólares, y sus filas conviven en esta lista."
              },
              "serie": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "El número con que el banco identifica esta transacción. Sólo lo publica la cartola de las cuentas en moneda extranjera; en las cuentas en pesos viene 'null' porque BCI no lo entrega. Sirve para conciliar contra la cartola del banco, no para ordenar."
              },
              "periodo": {
                "type": "string",
                "description": "El mes (AAAA-MM) bajo el que está archivada esta fila, y el valor con el que filtra el 'periodo' de la entrada. Significa dos cosas según la cuenta, porque BCI las sirve distinto: en una cuenta en PESOS es la ventana con que se pidió el sync, no una propiedad del movimiento; en una cuenta en MONEDA EXTRANJERA es el mes del propio movimiento, porque esa cartola no ofrece ventana de fechas: entrega sus últimos movimientos y punto. La fecha real vive siempre en 'fechaMovimiento'. Cadena vacía ('') en una cuenta en moneda extranjera significa que esa fecha no se pudo interpretar: la fila igual se guardó (su huella la distingue) y queda fuera de cualquier filtro por 'periodo', visible sólo sin ese filtro."
              },
              "fechaMovimiento": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "La fecha del movimiento (ISO 8601), tal como la entrega el banco. 'null' cuando no la trajo."
              },
              "fechaContable": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "La fecha contable del movimiento (ISO 8601), que puede diferir de 'fechaMovimiento'. 'null' cuando el banco no la trajo."
              },
              "descripcion": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "La glosa del movimiento, tal como la escribe el banco. 'null' cuando llega vacía."
              },
              "monto": {
                "anyOf": [
                  {
                    "type": "number"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "La magnitud del movimiento SIN signo. El sentido lo da 'type' y el signo visible, 'display'. 'null' significa que el banco no trajo la celda, nunca 0."
              },
              "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."
              },
              "category": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "La categoría con que el propio BCI clasifica el movimiento (por ejemplo 'Transferencias'). Es una etiqueta del banco, no un vocabulario de Connect: puede cambiar sin aviso. 'null' cuando el banco no la trae."
              },
              "mnemonico": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "El código corto de transacción del propio BCI (por ejemplo 'TRF'). Es una etiqueta del banco sin catálogo publicado: sirve para agrupar movimientos del mismo tipo, no para deducir qué fue la operación. 'null' 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. 'null' cuando el detalle no lo trae."
                  },
                  "rut": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El RUT de la contraparte, tal cual. 'null' cuando el detalle no lo trae."
                  },
                  "bank": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El banco de la contraparte. 'null' cuando el detalle no lo trae."
                  },
                  "account": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "El número de cuenta de la contraparte. 'null' cuando el detalle no lo trae."
                  }
                },
                "required": [
                  "name",
                  "rut",
                  "bank",
                  "account"
                ],
                "additionalProperties": false,
                "description": "La contraparte del movimiento, extraída del detalle que adjunta el banco. Los cuatro campos vienen en 'null' cuando el movimiento no trae detalle, que es lo normal fuera de las transferencias. Son datos personales de terceros: trátalos como tales."
              },
              "ultimaLecturaEn": {
                "type": "string",
                "description": "Instante (ISO 8601) en que esta fila se leyó del banco por última vez. Una corrección del banco entra como fila NUEVA en vez de reemplazar a la anterior, así que ante dos filas del mismo movimiento vale la de 'ultimaLecturaEn' mayor."
              }
            },
            "required": [
              "numeroCuenta",
              "currency",
              "serie",
              "periodo",
              "fechaMovimiento",
              "fechaContable",
              "descripcion",
              "monto",
              "type",
              "display",
              "saldoContable",
              "category",
              "mnemonico",
              "counterparty",
              "ultimaLecturaEn"
            ],
            "additionalProperties": false,
            "description": "El movimiento completo, igual que en 'bci_pyme.movimientos.consultar'. Un mismo movimiento puede validar UN solo pago: si ya lo usaste para otro, descártalo."
          }
        },
        "required": [
          "confianza",
          "motivos",
          "diferenciaDias",
          "movimiento"
        ],
        "additionalProperties": false
      },
      "description": "Hasta 20 movimientos que podrían ser la transferencia, la más probable primero. Vacía significa que no está en lo sincronizado hasta 'ultimaLecturaEn', no que no exista."
    },
    "ambigua": {
      "type": "boolean",
      "description": "True si hay más de una candidata con la mejor confianza: por ejemplo, dos transferencias del mismo RUT y monto en la ventana. No la des por validada sin otro dato que las distinga."
    },
    "ultimaLecturaEn": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "El último instante (ISO 8601) en que Connect leyó movimientos de esta conexión desde el banco. Una transferencia posterior todavía no puede aparecer. 'null' si nunca se sincronizó."
    },
    "completo": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "Si lo sincronizado cubre toda la ventana: false si el último sync de algún mes de la ventana quedó cortado (BCI entrega hasta 1000 movimientos por cuenta y mes) o si la ventana tenía más filas de las que la búsqueda revisa. 'null' si no se sabe. Con false o null, una búsqueda vacía no prueba nada."
    }
  },
  "required": [
    "candidatas",
    "ambigua",
    "ultimaLecturaEn",
    "completo"
  ],
  "additionalProperties": false
}