Mercado Livre BR — Seller Storefront Scraper API

🇺🇸 English | 🇧🇷 Português

What this does

Extract a Mercado Livre Brasil seller's full storefront — header (id, name, logo, total inventory) plus the paginated product catalog (up to ~2,000 items per seller). No API key, no scraping infrastructure, residential proxy included.

✓ Validated 2026-05-28: 200 products extracted across 5 paginated pages in 24s for seller TROCAFY (smoke test).

Quick example

Input:

{ "seller": "TROCAFY", "maxItems": 200 }

Output — dataset (1 item per product, real data from smoke test):

{
  "title": "Apple iPhone 11 (64 GB) - Preto - Bom (Recondicionado)",
  "price": "1179.00",
  "original_price": null,
  "discount": null,
  "currency": "BRL",
  "product_url": "https://www.mercadolivre.com.br/apple-iphone-11-64-gb-preto-bom-recondicionado/p/MLB2000091412",
  "image_url": "https://http2.mlstatic.com/D_Q_NP_2X_839025-MLA95685070222_102025-E.webp",
  "scraped_at": "2026-05-28T20:04:27.104983Z",
  "seller_name": "Trocafy",
  "seller_location": null,
  "seller_rating": null,
  "rating": null,
  "reviews_count": null,
  "installments": "10x R$ 117 , 90 sem juros",
  "categories": [],
  "badges": [],
  "sponsored": false,
  "shipping_free": true,
  "shipping_cost": null,
  "seller_id": "1156343076"
}

Output — key-value store, key SELLER (seller header, saved once per run):

{
  "seller_id": "1156343076",
  "name": "TROCAFY",
  "logo_url": "https://http2.mlstatic.com/D_NQ_NP_730508-MLA74532559107_022024-O.jpg",
  "total_results": 353
}

Accepted seller input formats

The actor accepts 3 formats and resolves them internally to the canonical _CustId_NNN URL:

Format	Example
Slug only	TROCAFY
/perfil/ URL	https://www.mercadolivre.com.br/perfil/TROCAFY
Canonical URL	https://lista.mercadolivre.com.br/_CustId_1156343076

Output fields (per-product, dataset)

Field	Type	Notes
title	string	Product name as shown on the seller's card.
price	string|null	Decimal serialized as string in JSON (ex. "1179.00"). BRL.
original_price	string|null	Pre-discount price (strikethrough). Same encoding as price.
discount	int|null	Discount percentage (ex. 15).
currency	string	Always "BRL".
product_url	string	Canonical URL, tracking params stripped.
image_url	string|null	Main product image.
seller_name	string|null	Store name as displayed on the card.
seller_location	string|null	Always null in v0.1 (PDP-only) — see Known limits.
seller_rating	float|null	Always null in v0.1 (PDP-only) — see Known limits.
rating	float|null	0.0–5.0 stars when shown.
reviews_count	int|null	Number of reviews when shown.
installments	string|null	Raw installment text.
categories	string[]	Always [] in v0.1 — see Known limits.
badges	string[]	Normalized tokens from {FULL, MAIS VENDIDO, OFERTA DO DIA, RECOMENDADO, FRETE GRÁTIS}.
sponsored	bool	True for ads slots.
shipping_free	bool	True when "Frete grátis" is displayed.
shipping_cost	string|null	Always null in v0.1 (rarely on SERP). Same encoding as price when present.
scraped_at	string	ISO 8601 UTC timestamp.
seller_id	string	Mercado Livre customer ID (constant within a run).

How to access the seller header

The seller header is saved once per run in the key-value store under the key SELLER. The dataset has one item per product; the seller metadata is in a separate key to avoid duplication.

from apify_client import ApifyClient

client = ApifyClient("apify_api_...")
run = client.actor("scrapersbr/mercadolivre-seller-storefront").call(
    run_input={"seller": "TROCAFY", "maxItems": 200}
)

# Products (1 per dataset item)
products = list(client.dataset(run["defaultDatasetId"]).iterate_items())

# Seller header (single record in KV store)
seller = client.key_value_store(run["defaultKeyValueStoreId"]).get_record("SELLER")["value"]
# {'seller_id': '1156343076', 'name': 'TROCAFY', 'logo_url': '...', 'total_results': 353}

Use cases

• Competitive intelligence: monitor a competitor's full catalog daily; detect new SKUs, price drops, discontinued items.
• Marketplace analytics: export an entire seller inventory to BigQuery / Sheets for category-level trend analysis.
• AI agents (Claude / Cursor): real-time access to a seller's inventory inside agent workflows.

Pricing

$1.49 per 1,000 results. No subscription. First 100 results free for testing. Parity with Mercado Livre Product Search.

Compliance

• Public data only — /perfil/* and /lista/_CustId_* are public endpoints; no login, no PII.
• Respects rate-limit conventions — randomized 200-800ms delays between pages.
• Apify Residential Proxy BR — used in production runs (default in input_schema). Required when running from datacenter IPs, which Mercado Livre blocks.
• User-Agent: realistic browser identification. The actor does not impersonate or identify as a known bot crawler — standard practice for commercial data services.

Known limits

• v0.1 does not cover Official Stores (Magalu, KABUM, etc.) — for those, use the Mercado Livre Search Actor with seller filter, or wait for v0.2.
• Seller reputation data (MercadoLíder badges, % good deals, total sales) is no longer in the public DOM as of 2026. Schema is intentionally lean — Seller{seller_id, name, logo_url, total_results}.
• Hard cap ~2,000 items per seller imposed by Mercado Livre itself (40 pages × 50 items). If you request maxItems: 5000, the actor collects everything available and finishes with SUCCEEDED — never silently truncates.

Support

Response within 24h via Apify issues.

Changelog

• 2026-05-28 v0.1 — Initial release.

---

🇧🇷 Português

O que faz

Extrai a vitrine completa de um vendedor do Mercado Livre Brasil — header (id, nome, logo, total de produtos) e o catálogo paginado completo (até ~2.000 itens por vendedor). Sem API key, sem infraestrutura de scraping, residential proxy incluso.

✓ Validado em 2026-05-28: 200 produtos extraídos em 5 páginas paginadas em 24s pro vendedor TROCAFY (teste integração).

Exemplo rápido

Entrada:

{ "seller": "TROCAFY", "maxItems": 200 }

Saída — dataset (1 item por produto): mesmo JSON acima.

Saída — key-value store, chave SELLER (header do vendedor, salvo 1× por run): mesmo JSON acima.

Formatos de input aceitos

O actor aceita 3 formatos e resolve internamente pra URL canônica _CustId_NNN:

Formato	Exemplo
Apelido do vendedor	TROCAFY
URL /perfil/	https://www.mercadolivre.com.br/perfil/TROCAFY
URL canônica	https://lista.mercadolivre.com.br/_CustId_1156343076

Campos de saída (por produto, no dataset)

Campo	Tipo	Notas
title	string	Nome do produto.
price	string|null	Decimal serializado como string no JSON (ex. "1179.00"). BRL.
original_price	string|null	Preço antes do desconto (riscado). Mesmo encoding de price.
discount	int|null	Desconto em % (ex. 15).
currency	string	Sempre "BRL".
product_url	string	URL canônica, sem tracking.
image_url	string|null	Imagem principal.
seller_name	string|null	Nome do vendedor como exibido no card.
seller_location	string|null	Sempre null na v0.1 (PDP-only) — ver Limites conhecidos.
seller_rating	float|null	Sempre null na v0.1 (PDP-only) — ver Limites conhecidos.
rating	float|null	0.0–5.0 estrelas.
reviews_count	int|null	Número de avaliações.
installments	string|null	Texto bruto do parcelamento.
categories	string[]	Sempre [] na v0.1.
badges	string[]	Tokens normalizados de {FULL, MAIS VENDIDO, OFERTA DO DIA, RECOMENDADO, FRETE GRÁTIS}.
sponsored	bool	true para slots patrocinados.
shipping_free	bool	true quando "Frete grátis" aparece.
shipping_cost	string|null	Sempre null na v0.1. Mesmo encoding de price quando presente.
scraped_at	string	Timestamp ISO 8601 UTC.
seller_id	string	ID do vendedor no Mercado Livre (constante dentro de 1 run).

Como acessar o header do vendedor

O header é salvo uma vez por run no key-value store sob a chave SELLER. O dataset tem um item por produto; o metadata do vendedor fica em chave separada pra não duplicar.

from apify_client import ApifyClient

client = ApifyClient("apify_api_...")
run = client.actor("scrapersbr/mercadolivre-seller-storefront").call(
    run_input={"seller": "TROCAFY", "maxItems": 200}
)

# Produtos (1 por item do dataset)
produtos = list(client.dataset(run["defaultDatasetId"]).iterate_items())

# Header do vendedor (1 registro no KV store)
vendedor = client.key_value_store(run["defaultKeyValueStoreId"]).get_record("SELLER")["value"]
# {'seller_id': '1156343076', 'name': 'TROCAFY', 'logo_url': '...', 'total_results': 353}

Casos de uso

• Inteligência competitiva: monitore o catálogo completo de um concorrente diariamente; detecte novos SKUs, quedas de preço, itens descontinuados.
• Análise de marketplace: exporte inventário inteiro de vendedores pra BigQuery ou Sheets pra análise de tendência por categoria.
• Agentes IA (Claude / Cursor): acesso em tempo real ao catálogo de um vendedor dentro do workflow do agente.

Preços

$1.49 por 1.000 resultados. Sem assinatura. Primeiros 100 grátis pra teste. Paridade com Mercado Livre Product Search.

Conformidade

• Apenas dados públicos — /perfil/* e /lista/_CustId_* são endpoints públicos, sem login, sem PII.
• Respeita convenções de rate-limit — delays randomizados 200-800ms entre páginas.
• Apify Residential Proxy BR — usado em runs de produção (default no input_schema). Obrigatório quando rodando a partir de IPs de datacenter, que o Mercado Livre bloqueia.
• User-Agent: identificação realista de browser. O actor não se passa por nem se identifica como bot crawler conhecido — prática padrão para serviços comerciais de dados.

Limites conhecidos

• v0.1 não cobre Lojas Oficiais (Magalu, KABUM, etc.) — para essas, use o Mercado Livre Search Actor com filtro por vendedor, ou aguarde v0.2.
• Dados de reputação do vendedor (badges MercadoLíder, % bons negócios, total de vendas) não estão mais no DOM público desde 2026. Schema é intencionalmente enxuto — Seller{seller_id, name, logo_url, total_results}.
• Hard cap de ~2.000 itens por vendedor imposto pelo próprio Mercado Livre (40 páginas × 50 itens). Se você pedir maxItems: 5000, o actor coleta todo o disponível e encerra com SUCCEEDED — nunca trunca em silêncio.

Suporte

Resposta em até 24h via issues do Apify.

Histórico

• 2026-05-28 v0.1 — Lançamento inicial.