API Mercado Libre: la guía del vendedor que quiere escalar

La API Mercado Libre es, para los vendedores que crecen, la línea que separa operar "a mano" de operar en serio. Todo lo que el panel web muestra (ventas, comisiones, salud del listing, publicaciones, mensajes) está expuesto como endpoints HTTP. Conectarse a ellos te deja automatizar lo que hoy consume horas cada semana.

Este artículo no es una documentación oficial (la tienes en developers.mercadolibre.com). Es una guía operativa: qué endpoints importan, cómo funciona el OAuth, qué rate limits son reales, y cuándo vale la pena hacerlo tú mismo versus usar una herramienta que ya los consume. Está basada en nuestra experiencia construyendo ListAndRank, que usa la API Mercado Libre en vivo todos los días para los 7 países de LATAM.

Qué es la API Mercado Libre (desde la perspectiva del vendedor)

La API es el conjunto de endpoints HTTP que MercadoLibre expone para que aplicaciones externas (tuyas o de terceros) puedan leer y modificar tu cuenta con permiso del usuario. Es la misma información que te muestra el panel web, pero servida como JSON en vez de HTML.

Ejemplos concretos de lo que puedes hacer con la API:

• Publicar 50 listings en una hora en lugar de 50 veces manualmente en el panel.
• Sincronizar stock entre tu ERP y tus publicaciones sin que nadie toque el panel.
• Cambiar precios masivamente según reglas (margen mínimo, competencia, promo).
• Leer las órdenes pagadas para calcular utilidad real por producto.
• Recibir notificaciones en tiempo real cuando entra una pregunta, se vende algo o cambia el estado de un listing.
• Auditar la salud de tus listings con el score oficial de MeLi.

No es solo para developers. Es para cualquier vendedor cuyo volumen operativo ya no cierra a mano. Cuando manejas 100+ publicaciones activas, la API deja de ser "opcional" y pasa a ser la única forma sostenible de operar.

Autenticación: OAuth 2.0 en 3 pasos

La API Mercado Libre usa OAuth 2.0 con authorization code flow. El concepto:

1. Tu app redirige al usuario a MeLi para que autorice el acceso.
2. MeLi devuelve un código de autorización a tu redirect URI.
3. Tu app intercambia ese código por un access token (que expira en 6 horas) y un refresh token (que dura más).

En código, el intercambio se ve así:

POST https://api.mercadolibre.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={APP_ID}
&client_secret={SECRET}
&code={AUTH_CODE}
&redirect_uri={REDIRECT_URI}

La respuesta incluye access_token, refresh_token, expires_in (21600 segundos = 6 horas), y user_id. Guardas esos tokens asociados al usuario en tu base de datos.

Detalle crítico sobre el refresh token: dura 6 meses y es single-use. Cada vez que lo usas para refrescar, MeLi te devuelve un nuevo refresh_token en la respuesta y el anterior queda invalidado. Si tu base se queda con el anterior después de refrescar, la próxima vez vas a recibir un error de token inválido y el usuario tendrá que volver a autenticarse. Guarda siempre el refresh_token de la última respuesta.

Refresh proactivo, no reactivo

Un error típico: refrescar el token cuando la API devuelve 401. El problema es que entre que detectas el 401 y lo refrescas, tu usuario vio un error. La mejor práctica es refrescar antes de que expire — cada 4 horas, por ejemplo, con un scheduled job.

En ListAndRank lo hacemos con un Cloud Function programada (refreshMeliTokens) que corre cada 4 horas y refresca todos los tokens de usuarios activos. Nunca hay un 401 por token expirado porque siempre se refresca antes.

Country gate

Cuando autenticas a un usuario vía OAuth, la respuesta de /users/me incluye el campo country_id (ej. "AR", "MX"). Ese campo define en qué sitio (MLA, MLM, etc.) opera ese usuario. Dos cuentas de dos países distintos tienen tokens totalmente separados y no se pueden mezclar.

Si tu aplicación solo soporta ciertos países, la validación tiene que ocurrir en el OAuth callback, antes de crear cualquier dato en tu base. Así lo hacemos nosotros: rechazamos el login si el country_id no está en la lista blanca antes de escribir nada en Firestore.

Los 8 endpoints que mueven la aguja

MeLi tiene decenas de endpoints. Estos son los que, en la práctica, cubren el 90% de los casos de uso de un vendedor que opera a volumen.

1. GET /users/me — identidad y reputación del vendedor

Devuelve tus datos: nombre, email, país, site ID, reputación (seller_reputation.level_id, power_seller_status). Es el primer endpoint que llamas después del OAuth.

2. POST /items — publicar un listing

El endpoint core para crear publicaciones. Recibe un JSON con title, category_id, price, currency_id, available_quantity, listing_type_id ("gold_special" para Clásica, "gold_pro" para Premium), pictures[], attributes[], shipping.

POST https://api.mercadolibre.com/items
Authorization: Bearer {ACCESS_TOKEN}

{
  "title": "Audífonos Inalámbricos JBL Tune 510BT Bluetooth Negro",
  "category_id": "MLM1055",
  "price": 1299,
  "currency_id": "MXN",
  "available_quantity": 10,
  "condition": "new",
  "buying_mode": "buy_it_now",
  "listing_type_id": "gold_special",
  "pictures": [{ "source": "https://..." }],
  "shipping": { "mode": "me2", "free_shipping": false },
  "attributes": [
    { "id": "BRAND", "value_name": "JBL" },
    { "id": "MODEL", "value_name": "Tune 510BT" }
  ]
}

Sin condition (new / used / refurbished) y sin buying_mode (buy_it_now típicamente), el POST devuelve 400 en la mayoría de las categorías. La descripción va en un endpoint separado: POST /items/{id}/description. Ese es uno de los gotchas: muchos vendedores nuevos asumen que la descripción va dentro del body de /items, pero no — MeLi separó el endpoint por razones históricas.

3. GET /categories/{id}/attributes — atributos requeridos de categoría

Antes de publicar, necesitas saber qué atributos son obligatorios para la categoría. Este endpoint devuelve la lista completa, con el tipo (string, number, boolean), si es obligatorio, y — cuando aplica — los values permitidos. Por ejemplo, para "Color" devuelve el conjunto de colores aceptados con sus IDs.

Publicar sin completar los atributos requeridos no solo da error: hace que tu listing no aparezca en los filtros laterales del buscador. Los filtros son donde está la conversión más alta.

4. GET /sites/{siteId}/listing_prices — fees reales por tipo de publicación

Este endpoint es el que alimenta nuestro Proyector de Margen. Dados un precio y una categoría, devuelve el costo real del listing (la comisión) desglosado por tipo de publicación. No hay adivinanzas: es el fee oficial que te van a cobrar.

GET https://api.mercadolibre.com/sites/MLM/listing_prices?price=1500&category_id=MLM1055

Te devuelve un array con listing_type_id, sale_fee_amount, sale_fee_details. Crítico para calcular margen antes de publicar.

5. GET /orders/search?seller={id} — órdenes pagadas

Motor de todo lo financiero. Filtrando por order.status=paid y por fechas, obtienes la lista de órdenes con su total_amount, order_items[].sale_fee, shipping.shipping_option, y demás datos para calcular utilidad real.

Paginación: MeLi devuelve 50 órdenes por página con paging.offset y paging.limit. Para historiales grandes, paginar es obligatorio.

6. GET /items/{item_id}/health — desglose de calidad del listing

Devuelve el score de calidad del listing (escala 0.0 – 1.0) junto con un desglose por grupo: title, pictures, description, attributes, shipping, price, cada uno con acciones sugeridas y posibles penalties. Es el endpoint que mejor refleja lo que el panel de MeLi muestra como "calidad de la publicación".

Existe también GET /item/{item_id}/performance (nótese el singular /item/, distinto del plural en /items) que devuelve un score numérico más compacto sobre el performance de visitas y conversión. Los dos endpoints son complementarios: /health para saber qué arreglar, /item/.../performance para ver cómo performa.

7. GET /sites/{siteId}/domain_discovery/search?q={query} — clasificación de categoría

Dado un texto ("remera blanca algodón hombre"), devuelve la categoría MeLi más probable. Útil para flujos donde el vendedor no elige manualmente la categoría: tú describes el producto, el endpoint sugiere dónde va. Lo usamos en el paso 1 del wizard para autoclasificar el listing.

8. Webhooks — notificaciones en tiempo real

En vez de hacer polling cada 5 minutos, puedes suscribirte a webhooks por tipo de evento: orders_v2, items, questions, messages. MeLi te hace un POST a tu endpoint cuando algo cambia. Tu backend reacciona en segundos.

Ejemplo de payload de webhook:

{
  "resource": "/orders/123456789",
  "user_id": 987654321,
  "topic": "orders_v2",
  "application_id": 1234567890,
  "attempts": 1,
  "sent": "2026-04-17T12:00:00.000Z",
  "received": "2026-04-17T12:00:00.123Z"
}

Nota importante: el webhook te da solo el resource path, no el contenido completo. Tienes que hacer una segunda llamada a ese recurso para obtener los datos actualizados.

Rate limits y gotchas

La API Mercado Libre no publica un tope diario claro; el límite operativo documentado es de hasta 1.500 requests por minuto por seller (vendedor), con topes específicos por endpoint que pueden ser menores. Pasarte de ese ritmo sostenido dispara un 429 Too Many Requests.

• 1.500 req/min por seller es el límite global, pero endpoints individuales tienen sus propios sublímites. Si tu catálogo tiene 500 SKUs y sincronizas stock cada hora vía batch, necesitas agrupar bien las llamadas para no saturar endpoints específicos en los picos.
• Soluciones: caché agresivo, sincronizaciones diferenciales (solo lo que cambió), y batch reads con /items?ids=id1,id2,id3 que trae hasta 20 items en una sola llamada.

Otros gotchas que aprendimos en producción:

• La descripción va en un endpoint separado de /items. Si lo omites, el listing se publica sin descripción.
• Las imágenes tienen que ser URLs públicas accesibles por MeLi. Si tu CDN requiere auth, falla silenciosamente.
• El listing_type_id se llama "gold_special" y "gold_pro", no "Clásica" y "Premium". La documentación no siempre es clara con ese mapeo.
• Los atributos tienen value_id y value_name. Para valores controlados (color, marca), hay que usar value_id; si no, MeLi puede rechazar el listing o dejarlo fuera de filtros.
• El refresh token se invalida si el usuario revoca permisos en su panel de MeLi. Hay que manejar ese error y pedirle re-autenticación.

3 casos de uso reales

Caso 1: sincronización de stock

Tu ERP (o planilla Excel conectada) tiene el stock real. MeLi tiene el stock publicado. Cada hora, un cron lee el stock del ERP, compara con el stock de cada listing (GET /items?ids=... en batch), y actualiza solo los que cambiaron (PUT /items/{id} con el campo available_quantity).

Tiempo ahorrado: si manejas 200 SKUs, pasas de 1-2 horas diarias de actualización manual a cero minutos.

Caso 2: pricing dinámico

Cada noche, lees los precios de los top 5 competidores de cada producto (vía GET /sites/{siteId}/search?q=...&category=...), aplicas una regla de negocio ("quiero estar 5% abajo del líder pero con margen mínimo del 20%"), y ajustas precios automáticamente.

La regla de negocio requiere que conozcas tu costo real (vía el Centro de Finanzas) — si no, pricing dinámico sin margen mínimo es la receta para vender más rápido y perder más plata.

Caso 3: auto-monitor de salud

Cada lunes, lees GET /items/{item_id}/health para todos tus listings activos. Los que tienen score < 0.7 (la escala es 0.0 – 1.0) se flagean con el grupo que está fallando (título, fotos, atributos, descripción, envío, precio) y los arreglas con prioridad.

Ese workflow, hecho a mano, requiere abrir cada listing en el panel y leer el score. Automatizado, te toma 3 minutos revisar 200 listings.

Build vs Buy: cuánto cuesta hacerlo tú

Un MVP útil de integración a la API Mercado Libre requiere, como mínimo:

• OAuth 2.0 con refresh tokens y proactive refresh.
• Manejo de errores y retries (401, 429, 500).
• Caché para respetar rate limits.
• Webhooks con verificación de origen.
• Logging y observabilidad (cuando algo falla en producción, ¿cómo lo detectas?).
• Lógica del país: 7 sitios con atributos, monedas y vocabulario distintos.

Rango realista: 40-80 horas de desarrollo senior para un MVP que funcione sin romperse. En escala, se triplican en mantenimiento cuando MeLi cambia algo (lo hace varias veces al año).

Antes de empezar a construir, evalúa:

• ¿Cuánto tiempo real te ahorraría una integración vs el costo de construirla?
• ¿Hay herramientas existentes que ya consumen la API y cubren tu caso?
• ¿Tu equipo tiene capacidad de mantener la integración a largo plazo?

Si tu caso es operar publicaciones con AI (listings, fotos, atributos), finanzas por producto, y sync de dashboard, ListAndRank ya consume todos los endpoints relevantes para los 7 países. Usamos /items para publicar, /sites/{siteId}/listing_prices para fees reales, /orders/search para órdenes, /items/{item_id}/health para el desglose de calidad, /domain_discovery/search para clasificación, y webhooks para notificaciones.

Si tu caso es más específico (un ERP propio, integración con Tiendanube o Shopify, flujos custom), construir es la respuesta. Solo entra sabiendo cuántas horas vas a firmar.

Cierre

La API Mercado Libre es la palanca que separa vendedor operativo de vendedor que escala. No es para todos: requiere tiempo, código, o la decisión consciente de pagar una herramienta que ya la consume. Pero cuando tu volumen ya no cierra a mano, no hay atajo.

Si todavía no tienes claras las bases del listing (título, atributos, fotos), arranca por cómo optimizar tus listings con IA. La API te deja automatizar un proceso — si ese proceso está mal, la automatización solo te hace fallar más rápido.

Para un panorama de casos donde la IA mueve la aguja en ecommerce (no solo MeLi), lee IA para ecommerce: qué automatizar y qué evitar.

Probar ListAndRank gratis →