# Mercado Pago > Piloto privado en preparación para consultar pagos recibidos, reembolsos y comisiones de Mercado Pago. Pendiente de completar la validación real; aún no habilitado para conectar cuentas. **Piloto privado en preparación.** La integración está pendiente de completar su validación con Mercado Pago real y aún no está habilitada para conectar cuentas. Esta guía describe el funcionamiento previsto para cuando se abra el piloto. `mercadopago` está diseñado para leer los **pagos que recibió** la cuenta de Mercado Pago de una empresa, con sus reembolsos y las comisiones informadas, y guardarlos en Connect para consultarlos sin volver a llamar a Mercado Pago. Cada conexión tendrá un `conn_…` que identifica la cuenta y viaja en toda llamada (en REST, el header `X-Connect-Connection`). Una vez validado, Emisso podrá habilitar el piloto por organización. El conector solo estará disponible en el catálogo, el alta y la ejecución de las organizaciones invitadas. **El alcance previsto es solo lectura.** Las herramientas del conector no permiten cobrar, reembolsar, cancelar, transferir ni administrar suscripciones en Mercado Pago. ## Qué necesitarás al habilitarse el piloto [#qué-necesitarás-al-habilitarse-el-piloto] Para participar en el piloto, **necesitas una cuenta en Mercado Pago que reciba los pagos de la empresa, y tu usuario debe ser su titular o tener permiso sobre ella.** Autorizarás con esa cuenta: Connect no creará cuentas ni las administrará. El formulario previsto pedirá **un solo dato, y no será un secreto**: | Campo | Qué es | | ----------------- | ------------------------------------------------------------------------ | | RUT de la empresa | La empresa a la que pertenece la cuenta de Mercado Pago. Lo declaras tú. | **Mercado Pago no confirma ese RUT.** Su autorización no informa a qué contribuyente pertenece la cuenta, así que Connect no tiene contra qué compararlo: el RUT queda como lo escribiste. Si conectas varias empresas, revisa que cada conexión lleve el RUT correcto. En el flujo previsto del piloto, el navegador sale a Mercado Pago para que apruebes el acceso y vuelve a Connect. **Connect no te pedirá tu contraseña de Mercado Pago.** Guardará cifrado el permiso emitido, sin mostrarlo al agente. ## Permisos previstos [#permisos-previstos] Para activar una conexión del piloto, Connect exigirá **lectura** (`read`) y **acceso sin conexión** (`offline_access`, para renovar el permiso sin pedirte que vuelvas a entrar). Mercado Pago puede incluir también permisos de escritura y de gestión de pagos en su consentimiento; Connect admitirá los permisos que reconoce, pero sus operaciones seguirán limitadas a consultar datos. No ejecutará cobros, cancelaciones ni devoluciones. Revisa los permisos que muestra Mercado Pago antes de autorizar. Si falta lectura o acceso sin conexión, o se concede algún permiso que Connect no reconoce, la autorización será rechazada y la conexión no se activará. ### La cuenta queda fijada [#la-cuenta-queda-fijada] La primera autorización fija **qué cuenta de Mercado Pago** lee la conexión, y la conexión no cambia de cuenta: si una nueva autorización de esa misma conexión llega con otra cuenta, Connect la rechaza. Para leer otra cuenta, conéctala en una conexión aparte. ### La misma cuenta en varias organizaciones [#la-misma-cuenta-en-varias-organizaciones] El piloto contempla conectar la misma cuenta de Mercado Pago en más de una organización de Connect. Cada conexión tendrá su propio permiso, sus propios datos y su propia bitácora; una organización no podrá ver lo guardado en otra. ### Revocar el acceso [#revocar-el-acceso] Una vez conectada la cuenta, podrás revocar el acceso de dos formas: * **Desde Mercado Pago:** en la configuración de seguridad de tu cuenta, donde aparecen las aplicaciones con acceso, quita la aplicación de Connect. Desde ese momento Mercado Pago rechaza el permiso y la próxima sincronización responde `connection_credential_required`. * **Desde Connect:** elimina la conexión. Eso detiene la sincronización; para que Mercado Pago también deje de reconocer el permiso, revócalo además desde tu cuenta. Para volver a leer la cuenta después de revocar, entra a **Ajustes** de la conexión y usa **Volver a autorizar** con la misma cuenta de Mercado Pago. La conexión conserva sus datos; si autorizas con otra cuenta, Connect rechaza el cambio: otra cuenta es otra conexión. ## El alcance [#el-alcance] El piloto contempla un alcance, `pagos`, con el permiso `mercadopago:read`. Una sola sincronización traerá pagos, reembolsos y comisiones mediante estas herramientas: | Tool | Qué hace | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `mercadopago.conexion.sincronizar` | Trae de Mercado Pago lo nuevo o actualizado y lo guarda. Es el único camino que llama a Mercado Pago por datos. | | `mercadopago.conexion.verificar` | Comprueba que la autorización siga vigente. No trae pagos. | | `mercadopago.pagos.consultar` | Lee los pagos recibidos ya guardados: estado, monto, moneda, lo reembolsado, el neto, las comisiones y cuándo se libera el dinero. | | `mercadopago.reembolsos.consultar` | Lee los reembolsos ya guardados de esos pagos, con su monto, estado y fecha. | Solo entran los pagos que **recibió** la cuenta conectada. Las compras que esa cuenta hizo a otros no se guardan. ## Sincronizar [#sincronizar] Ejemplo previsto para una conexión del piloto habilitada: ```bash curl -X POST https://connect.emisso.ai/api/v1/tools/mercadopago.conexion.sincronizar/execute \ -H "Authorization: Bearer connect_sk_..." \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{}}' ``` Respuesta ilustrativa: ```json { "data": { "periodo": "2026-10", "estado": "encolado", "jobId": "sjb_3h5j7k9m1n2p4q6r8s0t1", "yaEnCurso": false }, "meta": { "request_id": "req_...", "tool_id": "mercadopago.conexion.sincronizar", "plane": "read" } } ``` La llamada está diseñada para responder con `estado: "encolado"` y un `jobId`; el resultado de la corrida llegará por [webhook](/docs/operar/webhooks) o en el estado de la conexión. La cadencia automática prevista es cada cuatro horas. El sync no trabaja por mes: avanza por la fecha de última actualización de los pagos desde donde quedó la vez anterior, y completa hacia atrás el historial que Mercado Pago permite buscar. `periodo` es opcional y solo organiza la ejecución; un período que no es el corriente no vuelve a consultar Mercado Pago. Cada ejecución guarda los tramos completos y, si quedan pendientes, termina con estado `partial` y un `detalle` que los explica. La capacidad para cuentas con mucho volumen aún debe validarse antes de ampliar el piloto. Durante el piloto, los avisos de cambios en pagos **solo adelantarán la próxima sincronización**: no aportarán datos que se guarden. La sincronización programada permitirá recuperar los cambios aunque un aviso se pierda. ## Consultar [#consultar] Ejemplo previsto para una conexión del piloto habilitada, con datos ya sincronizados: ```bash curl -X POST https://connect.emisso.ai/api/v1/tools/mercadopago.pagos.consultar/execute \ -H "Authorization: Bearer connect_sk_..." \ -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \ -H "Content-Type: application/json" \ -d '{"input":{"desde":"2026-10-01","hasta":"2026-10-15","estado":"approved"}}' ``` Respuesta (datos ficticios): ```json { "data": { "pagos": [{ "pagoId": "1325001234", "estado": "approved", "estadoDetalle": "accredited", "fechaCreacion": "2026-10-14T15:02:11.000Z", "fechaAprobacion": "2026-10-14T15:02:13.000Z", "fechaActualizacion": "2026-10-14T15:02:13.000Z", "fechaLiberacion": "2026-10-28T15:02:13.000Z", "estadoLiberacion": "pending", "moneda": "CLP", "monto": "15990", "montoReembolsado": "0", "montoNetoRecibido": "15333", "comisiones": { "estado": "declaradas", "totalReceptor": "657", "detalle": [{ "tipo": "mercadopago_fee", "monto": "657", "pagador": "collector" }] }, "medioPago": "visa", "tipoMedioPago": "credit_card", "tipoOperacion": "regular_payment", "cuotas": 1, "referenciaExterna": "orden-8841", "descripcion": "Pedido web", "sincronizadoEn": "2026-10-14T16:00:02.000Z" }], "cobertura": { "desde": "2025-10-24T16:00:00.000Z", "hasta": "2026-10-14T15:58:00.000Z", "completa": true, "ventanasSinLeer": 0, "sincronizadoEn": "2026-10-14T16:00:02.000Z" }, "cursor": null }, "meta": { "request_id": "req_...", "tool_id": "mercadopago.pagos.consultar", "plane": "action" } } ``` Los filtros `desde` y `hasta` son días (`AAAA-MM-DD`) por fecha de creación del pago en hora de Chile; `estado` usa el código de Mercado Pago. Para seguir con la página siguiente, reenvía el `cursor` tal cual. ### Los importes son texto, con su moneda [#los-importes-son-texto-con-su-moneda] `monto`, `montoReembolsado`, `montoNetoRecibido` y las comisiones vienen como **decimal en texto** (`"15990"`, `"1250.5"`) y en la moneda de `moneda`. No los conviertas a un número de coma flotante para sumarlos, y no sumes importes de monedas distintas. Un importe en `null` significa que Mercado Pago no lo informó: **`null` no es cero**. ### Una comisión desconocida no es cero [#una-comisión-desconocida-no-es-cero] `comisiones.estado` dice cuánto se sabe: | Estado | Qué significa | | --------------------------- | ------------------------------------------------------------------------------------------------ | | `declaradas` | Mercado Pago informó el detalle; `totalReceptor` es la suma de lo que paga quien recibe. | | `sin_comisiones_declaradas` | Mercado Pago informó un detalle vacío y el neto recibido es igual al monto: la comisión es cero. | | `desconocidas` | Mercado Pago no la informó o no se pudo leer. **No la trates como cero**: dilo así. | ## Verdades operativas [#verdades-operativas] ### `cobertura` dice qué está guardado [#cobertura-dice-qué-está-guardado] Las dos tools de consulta devuelven `cobertura`. `completa` es `true` solo si el historial llegó al límite que Mercado Pago permite buscar y no quedó ningún tramo sin leer. **Con `completa` en `false`, una lista vacía o un total no prueban que no haya pagos**: el historial todavía se está completando o hay tramos (`ventanasSinLeer`) que no se pudieron leer enteros. `hasta` dice hasta cuándo está todo leído; lo posterior llega en la próxima sincronización. ### Lo que este conector no es [#lo-que-este-conector-no-es] * **El historial llega hasta 12 meses atrás.** La búsqueda de pagos de Mercado Pago no devuelve pagos más antiguos, así que Connect tampoco los tiene. * **No es una cartola.** Lista pagos recibidos y sus reembolsos; no incluye retiros, transferencias ni otros movimientos de la cuenta. * **No es el saldo.** No hay saldo ni movimientos en tiempo real: lo guardado es lo que leyó la última sincronización. * **Sin retiros ni liquidaciones.** Los reportes de liquidación y de retiros quedan fuera de esta versión. ### Un pago puede cambiar después [#un-pago-puede-cambiar-después] Un pago aprobado puede reembolsarse o recibir un contracargo semanas después. Cuando Mercado Pago lo actualiza, la sincronización siguiente guarda la versión nueva; `fechaActualizacion` dice cuál leíste. ## Errores previstos [#errores-previstos] | Código | Qué significa | Qué hacer | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `428 connection_credential_required` | Mercado Pago ya no acepta el permiso: se revocó, venció o la autorización no incluye lectura con acceso sin conexión. | En **Ajustes** de la conexión, usa **Volver a autorizar** con la misma cuenta de Mercado Pago. | | `502 upstream_error` | Mercado Pago no respondió a tiempo o limitó las consultas. | Reintenta más tarde. La sincronización programada lo reintenta sola y conserva lo ya guardado. | | `502 upstream_unexpected_response` | Mercado Pago rechazó una consulta por permisos del recurso o respondió con una forma que Connect no reconoce. | Avísanos: hay que revisar la aplicación de Connect o el conector. | Cuando la autorización deja de valer, la sincronización responde `connection_credential_required`; una caída o un límite de Mercado Pago responde `upstream_error` y no invalida la autorización. El envelope de cada código está en el [catálogo de errores](/docs/operar/errores). ## Próximos pasos [#próximos-pasos] * Las cuatro tools, con contrato completo: [referencia de `mercadopago`](/docs/referencia/mercadopago). * La separación entre escribir la caché y leerla: [Sincronizar y consultar](/docs/conceptos/sincronizar-consultar).