# Sincronizar Mercado Pago con estado de autorización de reportes
> Sincroniza pagos y, si pides egresos, retiros de «Todas las transacciones».
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ------------------------------------------------------------------ |
| **Tool ID** | `mercadopago.conexion.sincronizar_v2` |
| **Nombre MCP** | `mercadopago__conexion__sincronizar_v2` |
| **Conector** | `mercadopago` |
| **Plano** | `read` |
| **Alcances** | `pagos`, `egresos` |
| **Scope (permiso)** | `mercadopago:read` |
| **Auth** | `connection_credentials` |
| **Versión** | `2` |
| **Sensible** | sí |
| **Deprecado** | no |
| **Comportamiento** | readOnly=false, destructive=false, idempotent=true, openWorld=true |
> **Requiere conexión.** Indica cuál en cada llamada: header `X-Connect-Connection` en REST y campo `connectionId` en el `execute_write` de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de [`conexiones.estado.consultar`](/docs/referencia/conexiones/estado-consultar).
## Qué hace [#qué-hace]
Prefiere esta versión a mercadopago.conexion.sincronizar. El resultado ejecutado distingue omitted por falta de autorización de los parciales operativos. Revisa gestionReportes para la autorización, la capacidad, la acción humana y la ruta al panel, también al encolar. Consulta mercadopago.egresos.consultar\_v2 para el resultado guardado. Una lista vacía no demuestra cero retiros. No mueve dinero ni otorga consentimiento.
## Entrada [#entrada]
| Campo | Tipo | Requerido | Descripción | |
| ---------- | -------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `periodo` | string \`^\d{4}-(0\[1-9] | 1\[0-2])$\` | no | 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. |
| `alcances` | lista de `"pagos"` · `"egresos"` | no · default `["pagos"]` | 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'. | |
JSON Schema de entrada
```json
{
"$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"
]
}
}
}
}
```
## Salida [#salida]
| Campo | Tipo | Requerido | Descripción | |
| ------------------------------------- | ---------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `periodo` | string | sí | Período de ejecución en AAAA-MM. | |
| `estado` | `"encolado"` · `"completado"` | sí | '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` | string | null | no | 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. |
| `yaEnCurso` | booleano | no | '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. | |
| `results` | lista de objeto | no | Resultado por módulo después de ejecutar. Ausente en el recibo encolado; no significa una lista vacía de retiros. | |
| `results[].alcance` | `"pagos"` · `"egresos"` | sí | El módulo sincronizado. | |
| `results[].marcador` | string | no | 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. | |
| `results[].status` | `"ok"` · `"partial"` · `"failed"` · `"omitted"` | sí | Resultado del módulo: omitted requiere autorización humana; partial conserva datos incompletos y failed indica que falló la lectura. | |
| `results[].recordsSynced` | entero | sí | 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'. | |
| `results[].error` | string | no | 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. | |
| `results[].detalle` | string | no | 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. | |
| `results[].motivo` | `"falta_autorizar"` | no | Presente cuando egresos quedó omitido por falta de autorización. | |
| `gestionReportes` | objeto | sí | Autorización y capacidad persistidas al responder; encolar todavía no acredita lectura de retiros. | |
| `gestionReportes.autorizacion` | `"sin_autorizar"` · `"vigente"` · `"revocada"` | sí | Autorización humana para configurar y generar reportes. Es independiente del acceso a la conexión. | |
| `gestionReportes.capacidadHabilitada` | booleano | sí | Si soporte habilitó la gestión de reportes para esta organización; es distinta del consentimiento. | |
| `gestionReportes.motivo` | `"falta_autorizar"` · `"capacidad_no_habilitada"` · `"requiere_atencion"` | null | sí | Por qué hace falta una acción humana. null cuando no se necesita ninguna. |
| `gestionReportes.accionHumana` | `"autorizar_reportes"` · `"solicitar_habilitacion"` · `"revisar_reportes"` · `"ninguna"` | sí | La autorización sólo puede darla una persona propietaria o administradora en el panel; nunca la API ni MCP. | |
| `gestionReportes.ruta` | string | null | sí | Ruta relativa al panel de reportes de esta conexión. null si la capacidad no está habilitada y no existe permiso vigente que revocar. |
| `gestionReportes.avance` | objeto | no | Avance persistido cuando esté disponible. Su ausencia significa que esta respuesta todavía no lo informa. | |
| `gestionReportes.avance.historico` | objeto | sí | Lectura comprobada de las ventanas del histórico y sus fechas. | |
| `gestionReportes.avance.diario` | objeto | null | sí | Última solicitud diaria observada. null si no existe; no promete datos tras un plazo fijo. |
JSON Schema de salida
```json
{
"$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
}
```
## Errores de esta tool [#errores-de-esta-tool]
| Código | HTTP | Reintentable | Qué hacer |
| ---------------------- | ---- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `connection_disabled` | 403 | no | Reactívala en /connections o usa otra conexión del mismo sistema. |
| `connection_not_found` | 404 | no | Usa uno de los connectionId que lista el error, o revisa la conexión en /connections. No hace falta reactivar nada. |
| `alcance_not_enabled` | 403 | no | Habilita el alcance en /connections o quítalo del input de la sincronización. |
| `too_many_pending` | 429 | sí | Deja terminar los trabajos en curso antes de encolar más. |
La llamada solo encola: las fallas del sistema externo (credencial, sesión, caída del portal) no llegan en esta respuesta, sino en el trabajo: en `outcomes` y `last_error` de `GET /v1/syncs/{jobId}`, o en los webhooks `sync.succeeded` (un alcance que falló junto a otros que terminaron) y `sync.failed`.
Toda llamada puede devolver además los códigos transversales (`validation_error`, `unauthorized`, `scope_not_granted`, `rate_limited`, entre otros): el detalle vive en el [catálogo de errores](/docs/referencia/errores).
## Próximos pasos [#próximos-pasos]
* [`mercadopago.pagos.consultar`](/docs/referencia/mercadopago/pagos-consultar): lee el alcance `pagos` que esta sincronización escribe.
* [`mercadopago.reembolsos.consultar`](/docs/referencia/mercadopago/reembolsos-consultar): lee el alcance `pagos` que esta sincronización escribe.
* [`mercadopago.egresos.consultar_v2`](/docs/referencia/mercadopago/egresos-consultar_v2): lee el alcance `egresos` que esta sincronización escribe.
* [`mercadopago.egresos.consultar`](/docs/referencia/mercadopago/egresos-consultar): lee el alcance `egresos` que esta sincronización escribe.