Sincronizar Mercado Pago con estado de autorización de reportes

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "description": "Período de ejecución en AAAA-MM; si se omite, el mes actual en Santiago. No filtra los pagos: el sync avanza por fecha de actualización desde donde quedó, y un período anterior no vuelve a consultar.",
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
    },
    "alcances": {
      "default": [
        "pagos"
      ],
      "description": "Los módulos a sincronizar. 'pagos' trae pagos, reembolsos y comisiones. 'egresos' lee los retiros de los reportes «Todas las transacciones»; sólo se puede pedir si está habilitado en la conexión. Si se omite, 'pagos'.",
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "pagos",
          "egresos"
        ]
      }
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "periodo": {
      "type": "string",
      "description": "Período de ejecución en AAAA-MM."
    },
    "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 abre una sesión real contra 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": "Resultado por módulo después de ejecutar. Ausente en el recibo encolado; no significa una lista vacía de retiros.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "alcance": {
            "type": "string",
            "enum": [
              "pagos",
              "egresos"
            ],
            "description": "El módulo sincronizado."
          },
          "marcador": {
            "description": "Uso interno de Connect; no se publica. En GET /v1/syncs/{id}, la fila trae en su lugar 'motivo': qué pasó y quién tiene que actuar, de la lista cerrada del catálogo de errores.",
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "partial",
              "failed",
              "omitted"
            ],
            "description": "Resultado del módulo: omitted requiere autorización humana; partial conserva datos incompletos y failed indica que falló la lectura."
          },
          "recordsSynced": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Cuántos registros de este alcance escribió ESTA corrida. Es el trabajo de esta llamada, no el total acumulado que tienes guardado: para saber cuánto hay, consulta. Un 0 no significa por sí solo «no hay datos»; cuando el cero tiene una explicación, viene en 'detalle'."
          },
          "error": {
            "description": "Por qué este alcance no terminó bien. Presente solo cuando 'status' es 'failed'. Normalmente es un código del catálogo de errores; cuando el sistema externo truncó el listado es una etiqueta de resultado ('movimientos_truncated', 'cartolas_truncated') que no está en ese catálogo y que significa «se escribió lo que alcanzó a venir». Decide por el valor, nunca por el texto libre.",
            "type": "string"
          },
          "detalle": {
            "description": "Explicación en lenguaje llano, presente solo cuando el resultado necesita una. Existe para que un cero se pueda transmitir tal cual en vez de concluir «no hay datos»: transmítelo a quien pregunte en lugar de resumir el número solo.",
            "type": "string"
          },
          "motivo": {
            "description": "Presente cuando egresos quedó omitido por falta de autorización.",
            "type": "string",
            "enum": [
              "falta_autorizar"
            ]
          }
        },
        "required": [
          "alcance",
          "status",
          "recordsSynced"
        ],
        "additionalProperties": false
      }
    },
    "gestionReportes": {
      "type": "object",
      "properties": {
        "autorizacion": {
          "type": "string",
          "enum": [
            "sin_autorizar",
            "vigente",
            "revocada"
          ],
          "description": "Autorización humana para configurar y generar reportes. Es independiente del acceso a la conexión."
        },
        "capacidadHabilitada": {
          "type": "boolean",
          "description": "Si soporte habilitó la gestión de reportes para esta organización; es distinta del consentimiento."
        },
        "motivo": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "falta_autorizar",
                "capacidad_no_habilitada",
                "requiere_atencion"
              ]
            },
            {
              "type": "null"
            }
          ],
          "description": "Por qué hace falta una acción humana. null cuando no se necesita ninguna."
        },
        "accionHumana": {
          "type": "string",
          "enum": [
            "autorizar_reportes",
            "solicitar_habilitacion",
            "revisar_reportes",
            "ninguna"
          ],
          "description": "La autorización sólo puede darla una persona propietaria o administradora en el panel; nunca la API ni MCP."
        },
        "ruta": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Ruta relativa al panel de reportes de esta conexión. null si la capacidad no está habilitada y no existe permiso vigente que revocar."
        },
        "avance": {
          "description": "Avance persistido cuando esté disponible. Su ausencia significa que esta respuesta todavía no lo informa.",
          "type": "object",
          "properties": {
            "historico": {
              "type": "object",
              "properties": {
                "leidas": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "description": "Ventanas del histórico íntegramente respaldadas por CSV leídos. No cuenta solicitudes ni períodos sólo revisados."
                },
                "total": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991,
                  "description": "Ventanas de hasta 60 días que componen los 12 meses desde la autorización."
                },
                "periodosLeidos": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "desde": {
                        "type": "string",
                        "description": "Día calendario AAAA-MM-DD del reporte, en GMT-03 fijo."
                      },
                      "hasta": {
                        "type": "string",
                        "description": "Día calendario AAAA-MM-DD del reporte, en GMT-03 fijo."
                      }
                    },
                    "required": [
                      "desde",
                      "hasta"
                    ],
                    "additionalProperties": false
                  },
                  "description": "Intervalos de archivos leídos de forma completa; conserva los huecos entre intervalos."
                }
              },
              "required": [
                "leidas",
                "total",
                "periodosLeidos"
              ],
              "additionalProperties": false,
              "description": "Lectura comprobada de las ventanas del histórico y sus fechas."
            },
            "diario": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "fecha": {
                      "type": "string",
                      "description": "Día calendario AAAA-MM-DD del reporte, en GMT-03 fijo."
                    },
                    "estado": {
                      "type": "string",
                      "enum": [
                        "pedido",
                        "listo",
                        "leido",
                        "hueco"
                      ],
                      "description": "pedido: aún sin archivo listo comprobado. listo: archivo disponible, aún no leído por completo. leido: CSV íntegro guardado. hueco: sin lectura confirmada; revisa el estado del reporte."
                    }
                  },
                  "required": [
                    "fecha",
                    "estado"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "description": "Última solicitud diaria observada. null si no existe; no promete datos tras un plazo fijo."
            }
          },
          "required": [
            "historico",
            "diario"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "autorizacion",
        "capacidadHabilitada",
        "motivo",
        "accionHumana",
        "ruta"
      ],
      "additionalProperties": false,
      "description": "Autorización y capacidad persistidas al responder; encolar todavía no acredita lectura de retiros."
    }
  },
  "required": [
    "periodo",
    "estado",
    "gestionReportes"
  ],
  "additionalProperties": false
}