Sincronizar

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "minLength": 7,
      "maxLength": 7,
      "pattern": "^[1-9]\\d{3}-(?:0[1-9]|1[0-2])$",
      "description": "Mes en formato AAAA-MM. Con movimientos admite meses anteriores sujetos a disponibilidad; sin movimientos requiere el mes actual de Perú. Los saldos siempre representan el estado observado al sincronizar."
    },
    "alcances": {
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "saldos",
          "movimientos",
          "cartolas"
        ]
      },
      "description": "Saldos, con movimientos y/o cartolas opcionales. Cada lectura cubre todas las cuentas autorizadas."
    }
  },
  "required": [
    "periodo",
    "alcances"
  ],
  "additionalProperties": false
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "minLength": 7,
      "maxLength": 7,
      "pattern": "^[1-9]\\d{3}-(?:0[1-9]|1[0-2])$",
      "description": "Mes en formato AAAA-MM. Con movimientos admite meses anteriores sujetos a disponibilidad; sin movimientos requiere el mes actual de Perú. Los saldos siempre representan el estado observado al sincronizar."
    },
    "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",
            "enum": [
              "saldos",
              "movimientos",
              "cartolas"
            ],
            "description": "Alcance completado en esta lectura."
          },
          "status": {
            "type": "string",
            "const": "ok",
            "description": "El alcance terminó correctamente. Si falla, la sincronización devuelve un error; no entrega una lectura parcial como exitosa."
          },
          "recordsSynced": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Cantidad de cuentas, movimientos o PDF conservados para cada alcance."
          },
          "completo": {
            "type": "boolean",
            "const": true,
            "description": "La lectura terminó todas las cuentas y páginas del intervalo observado. No garantiza frescura actual ni que el día haya terminado."
          }
        },
        "required": [
          "alcance",
          "status",
          "recordsSynced",
          "completo"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "periodo",
    "estado"
  ],
  "additionalProperties": false
}