Mercado Pago

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

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:

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

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 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

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

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 piloto contempla un alcance, pagos, con el permiso mercadopago:read. Una sola sincronización traerá pagos, reembolsos y comisiones mediante estas herramientas:

Solo entran los pagos que recibió la cuenta conectada. Las compras que esa cuenta hizo a otros no se guardan.

Sincronizar

Ejemplo previsto para una conexión del piloto habilitada:

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:

{
  "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 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

Ejemplo previsto para una conexión del piloto habilitada, con datos ya sincronizados:

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):

{
  "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

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

comisiones.estado dice cuánto se sabe:

Verdades operativas

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

• 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 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

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.

Próximos pasos

• Las cuatro tools, con contrato completo: referencia de mercadopago.
• La separación entre escribir la caché y leerla: Sincronizar y consultar.