# Mercado Livre Scraper — busca, categorias e ofertas (8 países) (`synexa-oliveira/mercado-livre-scraper`) Actor

Produtos do Mercado Livre por busca, URL de categoria ou Ofertas do Dia: preço, desconto, parcelas, vendedor, loja oficial, nota, vendidos, frete grátis, FULL, imagem e link. 8 países. Lê o JSON estruturado da página, não o HTML.

- **URL**: https://apify.com/synexa-oliveira/mercado-livre-scraper.md
- **Developed by:** [Henrique Barbosa Lopes de Oliveira](https://apify.com/synexa-oliveira) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Mercado Livre Scraper — busca, categorias e Ofertas do Dia (8 países)

Extraia produtos do **Mercado Livre / Mercado Libre** em segundos: por termo de busca, por URL de categoria ou busca com filtros, ou a lista inteira de **Ofertas do Dia**. Funciona em **Brasil, Argentina, México, Chile, Colômbia, Peru, Uruguai e Equador**.

Você paga **por produto extraído** — nada de mensalidade. Uma busca de 100 produtos custa centavos de dólar.

> 🇺🇸 **English summary below.**

### O que você recebe por produto

| Campo | Exemplo |
|---|---|
| `id`, `title`, `url`, `image`, `thumbnail` | `MLB5312090728`, "Sapateira Organizador…", link direto, foto em alta |
| `price`, `original_price`, `discount_percent`, `currency` | `131.55`, `212`, `37`, `BRL` |
| `installments`, `installments_count`, `installments_value`, `installments_no_interest` | "4x 32.89 sem juros", `4`, `32.89`, `true` |
| `rating` | `4.8` |
| `sold_text`, `sold_min` | "+10mil", `10000` *(só em Ofertas do Dia — a busca do ML não mostra vendidos)* |
| `seller`, `official_store` | "Motorola", `true` |
| `free_shipping`, `shipping_text`, `fulfillment` | `true`, "Chegará grátis amanhã", `true` (enviado pelo FULL) |
| `labels`, `promotions`, `variations_text`, `trade_in` | `["OFERTA DO DIA"]`, `["3 OFF com Cupom"]`, "Disponível em 5 cores", `false` |
| `position`, `site`, `query`, `source_url`, `scraped_at` | posição no resultado, país, o que você pediu, de onde veio, quando |

Os dados vêm do **JSON estruturado que a própria página do Mercado Livre embute** (o mesmo que alimenta o card na tela), não de leitura visual do HTML. Isso torna a extração mais estável a mudanças de layout e mais precisa: preço é número, desconto é número, parcela é número.

### Como usar

1. **Termos de busca** — um por linha, como você digitaria no site: `fone bluetooth`, `air fryer 5 litros`.
2. **URLs** — cole o link de uma busca com filtros aplicados, de uma categoria ou de `/ofertas`. O país é detectado pelo domínio.
3. **Ofertas do dia** — marque a opção para varrer a página de ofertas do país escolhido (milhares de produtos com desconto, incluindo "vendidos").

Escolha o **país**, a **ordenação** (relevância, menor preço, maior preço) e **quantos produtos por consulta**. Pronto.

#### Exemplo de entrada

```json
{
  "searchTerms": ["fone bluetooth", "smartwatch"],
  "site": "MLB",
  "sort": "PRICE_ASC",
  "maxItemsPerQuery": 200
}
```

#### Exemplo de saída

```json
{
  "id": "MLB5312090728",
  "title": "Sapateira Organizador Sapatos Empilhável Vertical 6 Andares",
  "url": "https://produto.mercadolivre.com.br/MLB-5312090728-...",
  "price": 131.55,
  "original_price": 212,
  "discount_percent": 37,
  "currency": "BRL",
  "installments": "4x 32.89 sem juros",
  "rating": 4.8,
  "sold_text": "+10mil",
  "sold_min": 10000,
  "free_shipping": true,
  "fulfillment": true,
  "seller": null,
  "official_store": null,
  "labels": ["OFERTA DO DIA"],
  "image": "https://http2.mlstatic.com/D_NQ_NP_2X_726678-MLB85638884735_062025-F.webp",
  "position": 1,
  "site": "MLB",
  "scraped_at": "2026-09-20T21:30:00Z"
}
```

Exporte em JSON, CSV, Excel ou consuma pela API da Apify. Agende execuções diárias para monitorar preço e estoque de concorrentes.

### Para que serve

- **Monitorar preços** dos concorrentes em uma categoria, todo dia, sem abrir o site.
- **Pesquisa de produto**: o que vende, com que desconto, de qual loja oficial, com frete grátis ou FULL.
- **Afiliados**: encontrar ofertas do dia com maior desconto para divulgar.
- **Inteligência de mercado** em 8 países com um único actor.

### Sobre bloqueios (leia antes de rodar)

Desde o fim de 2025 o Mercado Livre **exige login** para visitantes que não reconhece e aplica um **desafio anti-robô em JavaScript**. Este actor resolve os dois sozinho: usa proxy residencial do país da loja (padrão) e abre um navegador com impressão digital realista **somente quando o desafio aparece** — uma vez por consulta, ~8 segundos. As páginas seguintes reaproveitam a sessão.

- Deixe o proxy no padrão (**Apify Proxy, grupo RESIDENTIAL**). Proxy de datacenter cai na tela de login.
- Se aparecer `exigiu login` no log, rode de novo: o ML rotaciona a decisão por IP.
- O ML limita a busca a **~42 páginas (~2.000 produtos)** por termo. Para mais, divida em termos ou filtros.

### Limitações

- `sold_text`/`sold_min` só aparecem no modo Ofertas do Dia — a busca do ML não exibe "vendidos" no card.
- Não extrai descrição completa, perguntas ou variações detalhadas da página do produto (modo detalhe em desenvolvimento).
- Brasil e Argentina foram validados em produção; os outros seis países usam a mesma página e o mesmo mecanismo.

### Suporte

Abra um **Issue** na aba do actor. Respondo em até 14 dias, normalmente muito antes. Se o Mercado Livre mudar o formato, o conserto sai como nova versão sem custo.

***

### 🇺🇸 English

**Mercado Libre Scraper** — extract products from Mercado Libre by search term, category URL or the full **Daily Deals** list, in **Brazil, Argentina, Mexico, Chile, Colombia, Peru, Uruguay and Ecuador**. Pay per product extracted, no subscription.

**Per product:** id, title, url, image, price, original price, discount %, currency, installments (text, count, value, interest-free flag), rating, sold count (deals mode only), seller, official-store flag, free shipping, FULL fulfillment flag, labels, coupons, variations, position, site, query, timestamp.

Data comes from the **structured JSON embedded in the page** (the same payload that renders the product card), not from brittle HTML parsing — prices, discounts and installments are numbers, not strings.

**Input:** `searchTerms` (list), `startUrls` (search/category/deals URLs), `scrapeOffers` (boolean), `site` (MLB, MLA, MLM, MLC, MCO, MPE, MLU, MEC), `sort` (RELEVANCE, PRICE\_ASC, PRICE\_DESC), `maxItemsPerQuery`.

**Anti-bot:** since late 2025 Mercado Libre requires login for unrecognised visitors and serves a JavaScript proof-of-work challenge. This actor handles both: residential proxy of the store's country by default, and a fingerprinted browser opened **only when the challenge appears** (~8 s, once per query). Keep the default proxy settings; datacenter proxies hit the login wall.

**Limits:** ~42 pages (~2,000 products) per search term (Mercado Libre's own cap). Sold counts only in deals mode. Brazil and Argentina validated in production; the other six countries share the same page format.

**Support:** open an Issue on the actor page — answered within 14 days, usually much sooner.

# Actor input Schema

## `searchTerms` (type: `array`):

Um termo por linha, como você digitaria na busca do Mercado Livre. Ex.: `fone bluetooth`, `air fryer 5 litros`.

## `startUrls` (type: `array`):

Cole URLs do Mercado Livre: resultado de busca com filtros, página de categoria ou `/ofertas`. O país é detectado pelo domínio.

## `scrapeOffers` (type: `boolean`):

Raspa a página de Ofertas do Dia do país escolhido (milhares de itens com desconto).

## `site` (type: `string`):

Usado para termos de busca e ofertas. URLs coladas mantêm o país do domínio.

## `sort` (type: `string`):

Ordem dos resultados de busca por termo. URLs coladas mantêm a ordenação da própria URL.

## `maxItemsPerQuery` (type: `integer`):

Cada termo, URL ou modo ofertas para ao atingir este número. Uma página tem ~48 produtos.

## `concurrency` (type: `integer`):

Quantas consultas (termos/URLs) rodam ao mesmo tempo.

## `proxy` (type: `object`):

O Mercado Livre exige login para visitantes que não reconhece. Proxy RESIDENTIAL do país da loja (padrão) passa; datacenter cai na tela de login. O país é escolhido automaticamente pelo site, a menos que você defina um.

## `debugSaveHtml` (type: `boolean`):

Grava o HTML bruto da primeira página de cada consulta no key-value store. Só para diagnosticar mudança de formato.

## Actor input object example

```json
{
  "searchTerms": [
    "fone bluetooth"
  ],
  "scrapeOffers": false,
  "site": "MLB",
  "sort": "RELEVANCE",
  "maxItemsPerQuery": 100,
  "concurrency": 3,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "debugSaveHtml": false
}
```

# Actor output Schema

## `products` (type: `string`):

Todos os produtos extraídos, um por linha: id, título, preço, desconto, parcelas, vendedor, nota, frete, imagem, link.

## `products_csv` (type: `string`):

A mesma tabela em CSV, para abrir no Excel ou Google Sheets.

## `summary` (type: `string`):

Páginas lidas, itens gravados e bloqueios encontrados em cada termo ou URL.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "fone bluetooth"
    ],
    "proxy": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("synexa-oliveira/mercado-livre-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["fone bluetooth"],
    "proxy": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("synexa-oliveira/mercado-livre-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "fone bluetooth"
  ],
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call synexa-oliveira/mercado-livre-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,synexa-oliveira/mercado-livre-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Xmaoal5fsi5LGmYWR/builds/XXRTuHqv5UyUnIQnw/openapi.json