Mercado Livre Brasil Scraper Pro

Actor profissional da Apify para extracao de dados publicos do Mercado Livre Brasil com arquitetura modular, baixo custo operacional e fallback inteligente.

Visao geral

Este actor foi projetado para cenarios profissionais de monitoramento de ecommerce, inteligencia de mercado e enriquecimento de catalogo.

Principios tecnicos:

• HTTP + Cheerio como fluxo principal para reduzir custo por execucao.
• Extracao de JSON embutido sempre que disponivel para maior estabilidade.
• Fallback com Playwright apenas quando necessario (bloqueio, HTML incompleto, dados criticos ausentes).

Modos de execucao

• search: coleta resultados de busca com paginacao.
• product: coleta detalhes completos de paginas de produto.
• store: coleta dados de loja oficial ou perfil de vendedor.
• offers: coleta itens da secao de ofertas.
• auto: detecta automaticamente o tipo da URL informada.

Principais funcionalidades

• Multi-source scraping: busca, categoria, produto, loja e ofertas.
• Auto-deteccao de tipo de URL no modo auto.
• Deduplicacao por itemId, canonicalUrl ou ambos.
• Retry com exponential backoff e tratamento de 403, 429 e 5xx.
• Suporte a proxy Apify para runs longos e maior resiliencia.
• Gravacao incremental no dataset para preservar dados em falhas parciais.
• Tipagem forte em TypeScript e testes unitarios de parser.

Destaques de input

Campos mais usados:

• mode, keyword, keywords, startUrls
• maxPages, maxItems, maxConcurrency
• includeProductDetails, includeShippingDetails, includeAttributes
• scrapeOffers, offersOnly, offersFilter, maxPagesOffers
• proxyConfiguration, useBrowserFallback, debug

Consulte o schema completo em .actor/input_schema.json.

Exemplos de input

Search (baixo custo)

{
  "mode": "search",
  "keyword": "webcam logitech",
  "maxPages": 2,
  "maxItems": 100,
  "includeProductDetails": false,
  "useBrowserFallback": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "BR"
  }
}

Product (detalhamento completo)

{
  "mode": "product",
  "startUrls": [
    "https://www.mercadolivre.com.br/webcam-hd-logitech-c270-com-microfone-embutido-hd/p/MLB18931576"
  ],
  "includeDescription": true,
  "includeAttributes": true,
  "includeReviewsSummary": true,
  "includeShippingDetails": true,
  "maxItems": 20
}

Offers

{
  "mode": "offers",
  "offersOnly": true,
  "offersFilter": "smartphone",
  "maxPagesOffers": 3,
  "maxItems": 120
}

Exemplos de output

Search item

{
  "searchKeyword": "webcam logitech",
  "searchUrl": "https://lista.mercadolivre.com.br/webcam-logitech",
  "page": 1,
  "position": 1,
  "sponsored": false,
  "title": "Webcam HD Logitech C270 com Microfone Embutido HD",
  "normalizedTitle": "webcam hd logitech c270 com microfone embutido hd",
  "productUrl": "https://www.mercadolivre.com.br/webcam-hd-logitech-c270-com-microfone-embutido-hd/p/MLB18931576",
  "canonicalUrl": "https://www.mercadolivre.com.br/webcam-hd-logitech-c270-com-microfone-embutido-hd/p/MLB18931576",
  "itemId": "MLB18931576",
  "price": 229.9,
  "currency": "R$",
  "discountPercent": 28,
  "shippingText": "Chegara gratis amanha",
  "freeShipping": true,
  "scrapeTimestamp": "2026-04-06T22:35:07.562Z"
}

Product detail

{
  "itemId": "MLB18931576",
  "title": "Webcam HD Logitech C270 com Microfone Embutido HD",
  "brand": "Logitech",
  "model": "C270",
  "price": 229.9,
  "currency": "BRL",
  "attributes": [
    { "name": "Resolucao", "value": "HD" }
  ],
  "shippingInfo": {
    "freeShipping": true,
    "estimatedDeliveryText": "Chega amanha"
  },
  "url": "https://www.mercadolivre.com.br/webcam-hd-logitech-c270-com-microfone-embutido-hd/p/MLB18931576",
  "canonicalUrl": "https://www.mercadolivre.com.br/webcam-hd-logitech-c270-com-microfone-embutido-hd/p/MLB18931576",
  "scrapeTimestamp": "2026-04-06T22:35:07.562Z"
}

Execucao local

npm install
npm run lint
npm run test
npm run build
npm run dev

Para executar com input local, use storage/key_value_stores/default/INPUT.json.

Execucao na Apify

• Configure o input no Console do actor.
• Ative proxy para cenarios de maior volume (RESIDENTIAL recomendado).
• Execute e acompanhe logs em tempo real.
• Baixe resultados no dataset padrao do run.

Configuracoes recomendadas de operacao

• Comece com maxPages e maxItems baixos para validar cobertura.
• Use includeProductDetails: true apenas quando precisar enriquecimento profundo.
• Mantenha useBrowserFallback: true para resiliencia, sem custo alto desnecessario.
• Para workloads maiores, configure proxyConfiguration + concorrencia moderada.

Limitacoes conhecidas

• O layout do Mercado Livre pode mudar sem aviso e exigir ajuste de seletores.
• Parte dos dados pode variar por categoria, seller e tipo de anuncio.
• Alguns campos podem depender de renderizacao dinamica em momentos especificos.

Nota de compliance

Este actor foi projetado para coletar dados publicos. Use de forma responsavel e em conformidade com termos aplicaveis, politicas da plataforma e legislacao vigente.