MercadoLibre Seller & Competition Monitor

Monitorea precios, posiciones y cambios de vendedores en MercadoLibre en 9 países de LATAM. Solo pagas por los cambios detectados en modo delta — los items sin cambios son gratis.

Monitor prices, positions, and seller changes on MercadoLibre across 9 LATAM countries. Pay only for changes detected in delta mode — unchanged items cost nothing.

---

Diferencias vs el incumbente (saswave)

Feature	Este actor	saswave (gratis)
Success rate	>95% con credenciales API	39.4% (HTML sin TLS)
Países soportados	9 (MLA, MLB, MLM, MCO, MLC, MPE, MLU, MEC, MRD)	Limitado
Modo delta	Si — solo cobra cambios	No
Precio por item	$0.003	$0.004
API oficial ML	Si (client_credentials OAuth)	No
Posición en ranking	Si (order_backend)	No
Buy Box tracking	Si (catalog_listing)	No
Power Seller status	Si (MercadoLíder Gold/Platinum)	No

---

Requisitos

Recomendado: Credenciales de API de MercadoLibre

Sin credenciales el actor usa HTML scraping con Googlebot UA (success rate ~70-80%). Con credenciales OAuth el success rate supera el 95%.

Registro gratuito en: https://developers.mercadolibre.com/

Pasos:

1. Crear una cuenta de desarrollador (gratis)
2. Crear una nueva app
3. Copiar el client_id y client_secret al input del actor

El token dura 6 horas y se refresca automáticamente durante el run.

---

Modos de operación

SEARCH — Búsqueda por keyword o categoría

{
  "mode": "SEARCH",
  "siteId": "MLA",
  "searchQueries": ["iphone 15", "samsung galaxy s24"],
  "maxResultsPerQuery": 100,
  "fetchSellerDetail": true
}

SELLER — Todos los listings de un vendedor

{
  "mode": "SELLER",
  "siteId": "MLA",
  "sellerIds": ["2386762620"],
  "fetchItemDetail": true
}

PRODUCT — Todos los vendedores de un producto catálogo

{
  "mode": "PRODUCT",
  "siteId": "MLA",
  "catalogProductIds": ["MLA1055308852"],
  "fetchSellerDetail": true
}

MONITOR — Delta: solo emite cambios

{
  "mode": "MONITOR",
  "siteId": "MLA",
  "searchQueries": ["iphone 15"],
  "deltaFields": ["price", "orderBackend", "freeShipping"],
  "monitorStoreName": "mi-monitor-iphone"
}

El primer run detecta todos los items como NEW (sin costo de delta-event). Los runs subsiguientes solo emiten los items que cambiaron.

---

Output del dataset

Cada item contiene hasta 50 campos. Campos principales:

Campo	Tipo	Descripción
itemId	string	ID del listing (ej. MLA2396453468)
title	string	Título del listing
price	number	Precio actual
originalPrice	number/null	Precio antes del descuento
discountPercent	number/null	Porcentaje de descuento calculado
orderBackend	number/null	Posición en el ranking de búsqueda
catalogListing	boolean	Si ganó el Buy Box del catálogo
sellerId	number	ID numérico del vendedor
sellerNickname	string	Nombre del vendedor
freeShipping	boolean	Envío gratis
fulfillment	boolean	Fulfillment FULL de MercadoLibre
sellerReputationLevel	string/null	"5_green", "4_light_green", etc.
powerSellerStatus	string/null	"platinum", "gold", "silver", null
availableQuantity	number/null	Stock (solo con fetchItemDetail=true)
deltaType	string/null	"NEW", "UPDATED", "REMOVED" (modo MONITOR)
threatScore	number/null	Score 0-100 de amenaza competitiva (MONITOR UPDATED)

---

Eventos de cobro (Pay per Event)

Evento	Precio	Cuándo
seller-snapshot	$0.003	Por cada item emitido al dataset
delta-event	$0.001	Por cada item con cambios detectados (MONITOR: solo UPDATED y REMOVED)
seller-detail-enrich	$0.0005	Por cada vendedor único enriquecido con /users/{id}

Nota sobre delta-event: Los items NEW del primer run no se cobran como delta. Solo los cambios reales (precio, stock, posición) generan cobro de delta-event.

---

Notas sobre campos nulos

• winRate, offerScore, offerShare: La API de MercadoLibre devuelve null para la mayoría de listings. Solo se popula para sellers con acceso a métricas avanzadas. Nunca se inventa un valor.
• availableQuantity: null si fetchItemDetail=false. El endpoint de search no devuelve el stock confiablemente.
• Teléfonos del vendedor: no disponibles en endpoints públicos. No se incluye el campo.

---

Mantenimiento y alertas

• Success rate esperado con credenciales API: >95%
• Success rate con HTML Googlebot: 70-80%
• Si el selector .ui-vpp-striped-specs desaparece del HTML, techSpecs pasa a null sin fallar el run
• Versión de la API de ML monitoreada: v3 REST (estable desde 2020)
• Contacto para bugs: crear issue en el repositorio del actor

---

Changelog

v0.1.0 (2026-07-10)

• Release inicial con modos SEARCH, SELLER, PRODUCT, MONITOR
• API OAuth client_credentials como capa primaria
• HTML Googlebot UA como capa secundaria para techSpecs
• Modo delta con named KV store persistente
• threatScore calculado para cambios UPDATED
• 9 países LATAM soportados