DEV Community: Javier Sivack

El refresh token de Mercado Libre es de un solo uso: cómo no desconectar a tus vendedores

Javier Sivack — Tue, 03 Nov 2026 14:34:41 +0000

Para devs que conectan cuentas de vendedores con OAuth y ven invalid_grant en los logs.

Conectar una cuenta de Mercado Libre por OAuth lleva una tarde. El problema aparece días
después: un vendedor que "se desconectó solo", una sincronización que dejó de andar a las 3 de
la mañana, un invalid_grant que nadie entiende. Muchas veces la causa es la misma: el refresh
token se usó dos veces.

Las dos reglas

Según la documentación de autenticación de Mercado Libre:

El access token dura 6 horas. Después hay que renovarlo.
El refresh token es de un solo uso. Cada renovación te devuelve uno nuevo y el anterior deja de servir.

(Para recibir refresh token, tu aplicación del DevCenter tiene que tenerlo activado.)

La renovación es un POST a https://api.mercadolibre.com/oauth/token:

grant_type=refresh_token
client_id=...
client_secret=...
refresh_token=...

La respuesta trae un access_token nuevo y un refresh_token nuevo. Si no guardás el
nuevo, la próxima renovación va a fallar. Ese es el primer error, y el más fácil de ver.

El segundo es más traicionero.

La carrera

Imaginá dos pedidos del mismo vendedor que salen casi juntos (un aviso de orden y un cron, por
ejemplo) justo cuando el token venció:

Pedido A: token vencido → renueva con R1 → recibe R2 → guarda R2
Pedido B: token vencido → renueva con R1 → invalid_grant

R1 ya se usó. Según cómo esté escrito tu código, el pedido B:

marca la cuenta como desconectada, aunque R2 quedó bien guardado,
o guarda datos viejos encima de R2 y ahí sí no queda ningún token que sirva,
o reintenta para siempre con un token que nunca va a andar.

En cualquiera de los tres casos el vendedor queda afuera, aunque nadie hizo nada mal. Y casi
nunca pasa en tus pruebas, porque ahí hay un pedido a la vez. Pasa en producción, con tráfico.

1. Renovar antes de que venza

No esperes al 401. Guardá cuándo vence el token (expires_in viene en segundos) y renová con
margen, antes de cada pedido:

const MARGIN_MS = 60 * 60 * 1000; // 1 hora

if (tokens.expiresAt - Date.now() > MARGIN_MS) return tokens.accessToken;
return (await refresh(userId)).accessToken;

Con una hora de margen, un pedido largo o un reloj un poco desfasado no usan un token vencido.
Si igual llega un 401, renová una sola vez y repetí el pedido. Si vuelve a dar 401, no insistas.

2. Una sola renovación a la vez por vendedor

Dentro de un proceso alcanza con guardar la renovación en curso y que los demás la esperen:

const inFlight = new Map<number, Promise<Tokens>>();

function refresh(userId: number) {
  const running = inFlight.get(userId);
  if (running) return running; // ya hay una: esperala

  const job = doRefresh(userId).finally(() => inFlight.delete(userId));
  inFlight.set(userId, job);
  return job;
}

Y dentro de doRefresh, releé el token antes de renovar: otra renovación pudo terminar
mientras esperabas. Si el que está guardado ya es nuevo, usalo y no gastes el refresh token.

3. Con varias instancias, el lock va en la base

El Map de arriba vive en la memoria de un proceso. En Vercel, en Lambda o con dos réplicas
detrás de un balanceador, cada instancia tiene el suyo y la carrera vuelve.

Si guardás los tokens en Postgres, un advisory lock por vendedor lo resuelve sin tablas extra:

await db.transaction(async (tx) => {
  // Bloquea solo a este vendedor, hasta el final de la transacción.
  await tx.query("SELECT pg_advisory_xact_lock($1::bigint)", [userId]);

  const current = await getTokens(tx, userId); // releer dentro del lock
  if (isFresh(current)) return current;        // otra instancia ya renovó

  const next = await refreshWithMeli(current.refreshToken);
  await saveTokens(tx, next);
  return next;
});

La segunda instancia espera el lock, relee, ve el token nuevo y no llama a Mercado Libre. La
transacción queda abierta durante la llamada a /oauth/token, pero es una sola por vendedor
cada varias horas.

4. `invalid_grant` no se arregla reintentando

Si la renovación devuelve invalid_grant, el refresh token ya no sirve: se usó, venció o el
vendedor le quitó el permiso a tu aplicación. Reintentar no sirve. Lo correcto es:

Marcar la cuenta como "hay que volver a conectar" y dejar de llamar a la API con ella.
Avisarle al vendedor (o a tu equipo) con el link para conectar de nuevo.

Si no lo marcás, cada cron y cada aviso vuelven a intentar, llenan los logs y nadie se entera
de que hay una cuenta caída.

Ojo: esto es seguro solo si ya evitaste la carrera (puntos 2 y 3). Si no, el invalid_grant del
pedido B de arriba te haría marcar como caída una cuenta que estaba bien.

Resumen

Problema	Qué hacer
El token vence a las 6 h	Renovar antes, con margen, no después del 401
El refresh token nuevo se pierde	Guardar siempre el que vuelve en cada renovación
Dos renovaciones en el mismo proceso	Una sola en curso por vendedor; el resto la espera
Dos renovaciones en instancias distintas	Lock por vendedor en la base y releer adentro
`invalid_grant`	Marcar la cuenta para reconectar; no reintentar

Armé todo esto en VentaKit, un starter de Next.js + TypeScript para la API de Mercado
Libre, con tests para cada caso: https://github.com/javiersivack/ventakit (gratis, MIT).
Además de los tokens, trae los avisos de órdenes a prueba de duplicados y desorden. La versión
Pro suma Postgres con el lock entre instancias, una conciliación por cron que recupera avisos
perdidos y un panel que muestra qué vendedores hay que reconectar:
https://ventakit-site.vercel.app/?utm_source=devto&utm_campaign=art1

Lo probé contra la API real de Mercado Libre con usuarios de prueba: en la demo, el token
venció sin que nadie lo usara y la siguiente corrida del cron lo renovó sola, sin desconectar
a nadie.

VentaKit está hecho con Claude, una IA, como compañero de programación: yo lo dirijo, lo pruebo
contra Mercado Libre real y respondo por él.

¿Preferís no integrarlo vos? Hago integraciones con Mercado Libre, Mercado Pago y otras APIs
para equipos y agencias: https://javiersivack.com/es?utm_source=devto&utm_campaign=ventakit-art1#contact

Webhooks de Mercado Pago que no pierden pagos (ni regalan accesos)

Javier Sivack — Wed, 28 Oct 2026 13:59:38 +0000

Para devs que ya integraron Checkout Pro y quieren dormir tranquilos.

Integrar el botón de pago de Mercado Pago lleva una tarde. Los problemas aparecen después,
en producción: un pago aprobado que nunca liberó el producto, un cliente al que le llegaron
dos emails de bienvenida, una orden que volvió a "pendiente" sola. Casi siempre la causa está
en el endpoint que recibe los webhooks.

Estos son los seis errores que más veo y cómo evitarlos.

1. No verificar la firma

Tu endpoint de webhooks es público: cualquiera puede mandarle un POST que diga "el pago 123
está aprobado". Mercado Pago firma cada notificación con el header x-signature:

x-signature: ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2...
x-request-id: 3b6d3d0e-...

v1 es un HMAC-SHA256, calculado con la clave secreta de tu aplicación, de este texto:

id:<data.id>;request-id:<x-request-id>;ts:<ts>;

Tres detalles que suelen fallar:

data.id sale de la query string (?data.id=123&type=payment) y va en minúsculas.
Si falta alguno de los valores, esa parte se omite entera (incluido su ;).
Compará con una función de tiempo constante (crypto.timingSafeEqual), no con ===.

const manifest = `id:${dataId.toLowerCase()};request-id:${requestId};ts:${ts};`;
const expected = createHmac("sha256", secret).update(manifest).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"));

Si la firma no coincide, respondé 401.

2. Confiar en el cuerpo del webhook

Aun con la firma verificada, el cuerpo solo te dice qué cambió, no cómo quedó. Tomá el
data.id y consultá el pago:

GET https://api.mercadopago.com/v1/payments/{id}

Esa respuesta es la fuente de verdad: estado, monto, moneda y external_reference. Como
efecto secundario, un webhook repetido o viejo se vuelve inofensivo, porque siempre leés el
estado actual.

3. Confiar en la URL de retorno

Cuando el comprador vuelve a tu sitio, Mercado Pago agrega parámetros como
?status=approved&payment_id=.... Cualquiera puede escribir esa URL a mano. La página de
retorno tiene que preguntarle el estado a tu servidor (que lo actualizó el webhook) y
mostrar "esperando confirmación" mientras siga pendiente.

4. Disparar efectos por cada notificación

Mercado Pago reintenta si no respondés a tiempo (tiene un timeout de 22 segundos), y a veces
manda dos notificaciones casi juntas. Si tu código hace "llegó un webhook de pago aprobado →
mandar email", vas a mandar emails duplicados.

La regla es disparar efectos por cambio de estado, no por notificación. En la base de
datos se hace con un compare-and-set:

UPDATE orders SET status = 'paid', payment_id = $2
WHERE id = $1 AND status = 'pending';
-- rowCount = 1 → este proceso hizo el cambio: dispará el efecto
-- rowCount = 0 → otro webhook ya lo hizo: no hagas nada

5. Aceptar cualquier transición

Las notificaciones no llegan necesariamente en orden. Si procesás un pending que llega
después del approved, la orden vuelve a pendiente y le cortás el acceso a alguien que pagó.
Definí qué transiciones son válidas y descartá las demás:

Desde	Puede pasar a
pending	paid, failed, in_dispute
failed	paid (el comprador reintentó con otra tarjeta)
paid	in_dispute, refunded, charged_back
refunded, charged_back	—

6. No validar el monto

Que el pago esté aprobado no significa que sea el pago que esperabas. Pasa más de lo que
parece: el precio llegó desde el navegador, cambiaste el precio y quedó una preferencia vieja
dando vueltas, o un link de pago se reutilizó para otra orden. A mí me pasó probando: la orden
era de 1.500 pesos argentinos y la cuenta de prueba era de Uruguay, así que el pago aprobado
llegó por 1.500 pesos uruguayos. Antes de marcar la orden como
pagada, compará transaction_amount y currency_id con lo que esperabas. Si no coinciden,
dejá la orden en revisión en vez de dar acceso.

Bonus: qué responder

Situación	Respuesta	Por qué
Firma inválida	401	No es de Mercado Pago
Pago inexistente (404 de la API)	200	La "notificación de prueba" del panel usa un id inventado; reintentar no sirve
La API falla o tu token es inválido	500	Mercado Pago reintenta y no perdés la notificación
Procesado (cambie o no el estado)	200	Listo

Ojo con el último caso: si tu access token está mal configurado y respondés 200, perdés
todas las notificaciones sin enterarte.

Armé todo esto en PagoKit, un starter de Next.js + TypeScript con tests para cada caso:
https://github.com/javiersivack/pagokit (gratis, MIT). La versión Pro suma suscripciones,
reembolsos, Postgres y un outbox con reintentos para que los efectos tampoco se pierdan:
https://pagokit-site.vercel.app

¿Preferís no integrarlo vos? Hago integraciones con Mercado Pago y otras APIs para equipos y agencias: https://javiersivack.com/es#contact