Conectar una cuenta de vendedor de Mercado Libre mediante OAuth puede resolverse en una tarde de trabajo. Sin embargo, el verdadero problema aparece días después: un vendedor que “se desconectó solo”, una sincronización que dejó de funcionar a las 3 de la mañana o un error invalid_grant que nadie alcanza a explicar. En la mayoría de los casos, la causa es la misma: el refresh token se utilizó dos veces. Este comportamiento, documentado por Mercado Libre, es una de las razones más frecuentes de desconexión no intencional en integraciones de comercio electrónico en América Latina, y afecta tanto a desarrolladores independientes como a agencias que gestionan decenas de cuentas.
El refresh token es de un solo uso: el error más común
El flujo de autenticación de Mercado Libre entrega un access_token con vigencia limitada y un refresh_token que permite renovarlo. La documentación oficial es clara: para recibir un refresh token, la aplicación debe tenerlo habilitado en el DevCenter. La renovación se hace con una petición POST a https://api.mercadolibre.com/oauth/token, y la respuesta incluye un nuevo access_token y un nuevo refresh_token. Si el nuevo refresh token no se guarda, la siguiente renovación fallará. Ese es el primer error y el más visible.
Pero hay una trampa más sutil: el refresh token es de un solo uso. Una vez utilizado, queda invalidado. Si dos procesos intentan renovar al mismo tiempo —por ejemplo, el aviso de una orden y un cron que se ejecutan casi simultáneamente—, solo uno de ellos tendrá éxito. El otro recibirá un invalid_grant y, dependiendo de cómo esté escrito el código, el vendedor quedará desconectado aunque nadie haya hecho nada mal. Este escenario es casi imposible de reproducir en pruebas con un solo pedido a la vez, pero es común en producción con tráfico real.
Estrategias para evitar la desconexión
La solución requiere anticiparse a la expiración y coordinar los procesos que comparten credenciales. A continuación, las prácticas recomendadas:
- No esperar al error 401. Guarda el momento de expiración del token (el campo
expires_inviene en segundos) y renueva con margen antes de cada pedido. Una hora de margen es suficiente para cubrir pedidos largos o relojes desfasados. - Si llega un 401, renovar una sola vez y reintentar. Si vuelve a fallar, no insistir.
- Dentro de un mismo proceso, serializar la renovación. Guarda la renovación en curso y haz que los demás procesos esperen. Antes de renovar, relee el token almacenado: otra renovación pudo haber terminado mientras esperabas. Si el token ya es nuevo, úsalo y no gastes el refresh token.
- En entornos distribuidos, usa un bloqueo a nivel de base de datos. Un
Mapen memoria no funciona en Vercel, Lambda o con múltiples réplicas detrás de un balanceador. Si almacenas los tokens en PostgreSQL, un advisory lock por vendedor resuelve el problema sin tablas adicionales. 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.
Qué hacer cuando el refresh token ya no sirve
Si la renovación devuelve invalid_grant, el refresh token ya no es válido: se usó, venció o el vendedor revocó el permiso de la aplicación. Reintentar no sirve. Lo correcto es marcar la cuenta como caída y notificar al vendedor para que vuelva a autorizar la aplicación. Si no se marca, cada cron y cada aviso seguirán intentando, llenarán los logs y nadie se enterará de que hay una cuenta desconectada.
Es importante señalar que esta acción es segura solo si ya se evitó la carrera de renovaciones (puntos anteriores). De lo contrario, un invalid_grant provocado por una segunda renovación simultánea podría marcar como caída una cuenta que en realidad estaba bien.
Una herramienta de código abierto para implementar estas soluciones
Para facilitar la implementación, existe VentaKit, un starter de Next.js y TypeScript para la API de Mercado Libre, disponible en GitHub bajo licencia MIT. Incluye pruebas para cada caso y, además del manejo de tokens, incorpora avisos de órdenes a prueba de duplicados y desorden. La versión Pro añade PostgreSQL con el bloqueo entre instancias, una conciliación por cron que recupera avisos perdidos y un panel que muestra qué vendedores necesitan reconectar.
El autor probó la herramienta 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 ejecución del cron lo renovó automáticamente, sin desconectar a ningún vendedor. VentaKit fue desarrollado con Claude, una IA, como compañero de programación, pero el autor dirige, prueba contra Mercado Libre real y responde por el código.
Para equipos y agencias que prefieren no integrar la herramienta por su cuenta, el autor también ofrece servicios de integración con Mercado Libre, Mercado Pago y otras APIs.
Conclusión
El manejo correcto del refresh token es crucial para mantener conectadas las cuentas de los vendedores. Implementar renovaciones anticipadas, serializar las renovaciones dentro de un proceso y usar bloqueos distribuidos en entornos con múltiples instancias son pasos esenciales para evitar desconexiones inexplicables. Si tu aplicación ya está experimentando estos problemas, revisa el flujo de renovación y considera adoptar las prácticas descritas. La experiencia de miles de integraciones en la región demuestra que este detalle, aunque pequeño, marca la diferencia entre una integración estable y una que falla en silencio.