Skip to main content

Integración con MercadoLibre

MercadoLibre — cómo configurar, instalar y usar la integración con MercadoLibre. ↓ tiendanube · ⬆ intro de la sección

Esta guía explica todo el proceso necesario para configurar, instalar y utilizar la integración de MercadoLibre en la plataforma, tanto desde el lado del administrador del sistema como desde la experiencia del cliente final.

1. Creación de la Aplicación en MercadoLibre​

Para poder conectarse con la API de MercadoLibre, es necesario crear una aplicación (App) en el portal de desarrolladores.

  1. Ingresa al Portal de Desarrolladores de MercadoLibre.
  2. Inicia sesión con una cuenta de MercadoLibre.
  3. Ve a Mis Aplicaciones y selecciona Crear nueva aplicación.
  4. Completa la información solicitada (Nombre, Descripción corta, Categoría, etc.).
  5. Configuración de URIs de Redirección (Callback URLs):
    • Es mandatorio configurar los URI de redirección (Redirect URI) permitidos.
    • Debes agregar la URL exacta donde tu entorno recibe el callback de OAuth.
    • Ejemplo de URL de redirección: https://tu-dominio.com/api/admin/mercadolibre/oauth/callback (o http://localhost:83/... para desarrollo local).
  6. Permisos Sensibles (Scopes):
    • Habilita los permisos necesarios según lo que el sistema vaya a leer o escribir (por ejemplo: read, write, offline_access).
  7. Una vez guardada, MercadoLibre te proporcionará dos credenciales vitales:
    • App ID (Client ID)
    • Secret Key (Client Secret)

2. Configuración de Variables de Entorno​

La plataforma está diseñada para utilizar credenciales globales inyectadas desde las variables de entorno para que el usuario final no tenga que preocuparse por administrar Client IDs o Client Secrets.

En tu archivo .env o gestor de secretos, debes configurar:

GLOBAL_MERCADOLIBRE_CLIENT_ID="TU_APP_ID"
GLOBAL_MERCADOLIBRE_CLIENT_SECRET="TU_SECRET_KEY"
GLOBAL_MERCADOLIBRE_REDIRECT_URI="https://tu-dominio.com/api/admin/mercadolibre/oauth/callback"

El servicio user-service leerá automáticamente estas credenciales. Por lo tanto, el cliente solo necesita iniciar la autorización para obtener los Tokens.

3. Proceso Visual de Autorización para el Cliente​

Desde la plataforma (Portal Admin), el cliente final solo necesita seguir estos pasos para autorizar su cuenta y comenzar a sincronizar datos:

  1. El usuario se dirige a la sección "Integración MercadoLibre" en la administración del portal.
  2. Si no tiene conexión activa, se le presenta una tarjeta visual con un botón central que dice "Conectar Cuenta" o "Autorizar con MercadoLibre".
  3. Al hacer clic, se abre una ventana emergente (popup / pestaña nueva) que lo redirige al flujo oficial de autenticación de MercadoLibre.
    • El sistema generó automáticamente este enlace mezclando tu Client ID y el Redirect URI configurados en las variables de entorno.
  4. En esa ventana, el usuario debe iniciar sesión con su propia cuenta de MercadoLibre y conceder permisos a tu App.
  5. Tras aceptar, MercadoLibre lo redirige a la URL de callback configurada internamente.
  6. La plataforma recibe un código temporal (code), lo intercambia internamente por un access_token y un refresh_token, los encripta, y los asocia a la identidad del usuario en el sistema ("Cuentas Vinculadas").
  7. La ventana emergente se cierra automáticamente y la página principal de la plataforma se actualiza para mostrar un estado "CONECTADO" (Badge en color verde). A partir de este momento, se mostrarán detalles técnicos como su "ID de usuario " y las fechas de expiración de sus tokens.

Renovar / Actualizar​

Si el access token expira, el sistema intentará utilizar el refresh token de manera invisible. En el caso excepcional de que el usuario haya revocado el acceso desde MercadoLibre o haya expirado todo por completo, se le mostrará que la credencial está "EXPIRADA", pudiendo repetir el proceso haciendo clic en "Actualizar Credenciales".