# Shopee Brasil Scraper — Produtos, Preços, Vendidos e Lojas (`paulovitor18/shopee-brasil-produtos`) Actor

Veja preço, desconto e reputação da loja de cada produto da Shopee Brasil. Busque por palavra-chave ou URL de loja e receba preço (marcando quando é no Pix), nota, cidade de envio, loja com nota e avaliações e vendidos com período quando a Shopee publica. Sem login. Pague por resultado.

- **URL**: https://apify.com/paulovitor18/shopee-brasil-produtos.md
- **Developed by:** [MoreLock](https://apify.com/paulovitor18) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Shopee Brasil Scraper — Produtos, Preços, Vendidos e Lojas

Preço, desconto, nota, cidade de envio e a loja com nota e avaliações para cada produto da shopee.com.br, a partir de uma palavra-chave, de uma loja ou de um produto.

### O que sai de cada execução

Você digita `air fryer` e recebe uma linha por produto: nome, preço em R$ (marcando quando é o preço no Pix), preço riscado quando o card mostra, desconto, nota, de onde a Shopee envia e a URL. Com a consulta de loja ligada, a mesma linha ganha o nome da loja, a nota dela e quantas avaliações ela acumulou. Quando a Shopee publica vendidos para o produto, eles vêm junto, com o período: acumulado (`total`) ou dos últimos 30 dias (`mensal`).

Quatro comportamentos pesam na hora de confiar no resultado:

- **Busca sem resultado real volta vazia e não é cobrada.** Para um termo que não existe, a Shopee não devolve página vazia, e sim uns 40 produtos de recomendação genérica. O actor reconhece a troca e entrega zero linha.
- **Mudança de layout retém o lote sem cobrar.** Se mais de 20% dos produtos de um lote falham na validação, nada daquele lote sai nem é cobrado, e o resumo da execução marca `LAYOUT_SUSPEITO`.
- **Campos e motivos de nulo em português.** Todo campo vazio de loja ou de vendidos vem com a explicação (`loja_motivo_nulos`, `vendidos_motivo_nulo`).
- **Aceita URL de loja e de produto.** Cole `https://shopee.com.br/shop/<id>` para listar a vitrine da loja, ou a URL de um produto para receber só aquele produto.

Não precisa de login nem de cookie, e o actor não abre navegador.

### Recursos

- **Busca por palavra-chave em 6 ordenações.** A Shopee mostra produtos diferentes em relevância, mais vendidos, populares, mais recentes, menor preço e maior preço. O actor percorre as ordenações até completar o máximo pedido, sem produto repetido na execução.
- **Loja por URL**: lista a vitrine pública da loja, já com nome, nota e avaliações dela.
- **Produto por URL**: entrega só o produto pedido. Se ele não aparece na vitrine da loja, o actor procura pelo nome exato do produto.
- **Loja anexada ao produto**: nome, nota (0 a 5) e número de avaliações, com cache por loja (dez produtos da mesma loja custam uma consulta) e teto configurável.
- **Vendidos com procedência**: `vendidos` é o limite inferior do rótulo da Shopee (`30mil+` vira 30000), acompanhado de `vendidos_periodo` (`total` ou `mensal`) e `vendidos_origem`.
- **Preço no Pix sinalizado**: na maioria dos cards a Shopee mostra o preço pagando no Pix, sem preço riscado; nesses casos `preco_no_pix` vem `true`.
- **Cidade de envio** de cada card, inclusive `Internacional`.
- **Validação antes de cobrar**: todo produto passa por checagem de forma (nome, preço, faixas, coerência entre campos) antes de entrar no dataset. O que não passa fica registrado no resumo e não é cobrado.
- **Bloqueio não apaga o que já veio**: se a Shopee bloquear no meio de uma busca, o que já foi coletado é entregue e o resumo diz onde parou (`motivo_parada: bloqueio`).

### Exemplo de entrada

```json
{
  "palavrasChave": ["air fryer", "fone jbl"],
  "urls": ["https://shopee.com.br/shop/1515741369"],
  "maxItensPorBusca": 100,
  "enriquecerLoja": true,
  "maxLojas": 40
}
```

### Exemplo de saída

Linhas reais de uma execução de 14/09/2026 (busca `air fryer`):

```json
[
  {
    "nome": "Fritadeira Elétrica Air Fryer Mondial Family AF-30 3,5L Preta - 220V",
    "preco": 198,
    "preco_original": null,
    "preco_no_pix": true,
    "desconto_pct": 10,
    "nota": 4.9,
    "cidade_envio": "Bahia",
    "shop_id": "1050213612",
    "item_id": "18199069887",
    "url": "https://shopee.com.br/product/1050213612/18199069887",
    "loja_nome": "Le biscuit®",
    "loja_nota": 4.85,
    "loja_avaliacoes": 568388,
    "loja_url": "https://shopee.com.br/lebiscuit",
    "loja_origem_dados": "pagina_da_loja",
    "loja_motivo_nulos": null,
    "vendidos": null,
    "vendidos_label": null,
    "vendidos_periodo": null,
    "vendidos_origem": null,
    "vendidos_motivo_nulo": "a busca da Shopee nao publica vendidos; o item nao esta entre os destaques da loja",
    "termo": "air fryer",
    "ordenacao": "relevancia",
    "pagina": 0,
    "posicao": 1,
    "relevante_ao_termo": true
  },
  {
    "nome": "AirFryer Fritadeira Digital Uranyx 4L 1500w de Vidro Tela Touch 110-220v",
    "preco": 394.17,
    "preco_original": null,
    "preco_no_pix": true,
    "desconto_pct": 43,
    "nota": 5,
    "cidade_envio": "São Paulo",
    "shop_id": "1725800210",
    "item_id": "58212957869",
    "url": "https://shopee.com.br/product/1725800210/58212957869",
    "loja_nome": "rl5n_2upcx",
    "loja_nota": 4.85,
    "loja_avaliacoes": 505,
    "loja_url": "https://shopee.com.br/b4r60_",
    "loja_origem_dados": "pagina_da_loja",
    "loja_motivo_nulos": null,
    "vendidos": 427,
    "vendidos_label": "427 Vendido/Mês",
    "vendidos_periodo": "mensal",
    "vendidos_origem": "destaques_da_loja",
    "vendidos_motivo_nulo": null,
    "termo": "air fryer",
    "ordenacao": "relevancia",
    "pagina": 0,
    "posicao": 5,
    "relevante_ao_termo": true
  }
]
```

Além do dataset, cada execução grava um resumo no registro `OUTPUT` do key-value store, com `status` (`ok`, `parcial`, `sem_resultados`, `entrada_invalida`, `layout_suspeito`, `limite_de_gasto_atingido` ou `falhou`), por que cada busca parou (`motivo_parada`), quantos produtos vieram de cada ordenação, lojas não encontradas, produtos pedidos por URL e como foram achados, entradas recusadas com o motivo e a contagem dos eventos cobrados. Execução parcial também deixa o resumo na mensagem de status do Console.

### Parâmetros

| Campo | Tipo | Padrão | O que faz |
|---|---|---|---|
| `palavrasChave` | lista de texto | `[]` (o formulário já vem com `air fryer`) | Termos buscados na shopee.com.br, um por linha. |
| `urls` | lista de texto | `[]` | URLs de busca (`/search?keyword=`), de loja (`/shop/<id>`, lista a vitrine) ou de produto (entrega só o produto). URL de outro site é recusada sem consulta. |
| `maxItensPorBusca` | inteiro (1-500) | `50` | Produtos únicos por palavra-chave ou loja pedida. |
| `maxPaginasPorBusca` | inteiro (1-10) | `5` | Páginas por ordenação. Dentro de uma ordenação, a busca passa para a próxima quando uma página traz menos de 5 produtos novos. |
| `ordenacoes` | lista | as 6 | Ordenações percorridas, na ordem: `relevancia`, `mais_vendidos`, `populares`, `mais_recentes`, `menor_preco`, `maior_preco`. |
| `enriquecerLoja` | sim/não | `true` | Anexa nome, nota e avaliações da loja a cada produto. Cobra o evento `loja_enriquecida` 1 vez por loja resolvida. |
| `maxLojas` | inteiro (0-500) | `40` | Teto de lojas novas consultadas por execução para enriquecer buscas. Lojas pedidas por URL não contam. |
| `proxyGrupo` | `DATACENTER` / `RESIDENTIAL` | `DATACENTER` | Proxy da Apify usado nas páginas. |
| `reservaResidencial` | sim/não | `true` | Depois de esgotar as tentativas por datacenter, faz mais uma por IP residencial do Brasil. |
| `tentativas` | inteiro (1-5) | `3` | Tentativas por página em bloqueio ou erro de rede, com IP novo e espera crescente. |
| `timeoutMs` | inteiro | `30000` | Limite por requisição. |
| `salvarHtmlBruto` | sim/não | `false` | Grava o HTML de cada página no key-value store (diagnóstico). |

### Dicas

- **Volume**: com as 6 ordenações e até 3 páginas por ordenação, as medições deram 251 a 338 produtos únicos por termo (`air fryer` 311, `fone jbl` 251, `capinha iphone` 338). Só com relevância e até 10 páginas, deram 64 a 138. O actor para assim que atinge o `maxItensPorBusca`, então pedir 50 não gasta as outras ordenações.
- **Só precisa de preço?** Desligue `enriquecerLoja`. A execução fica bem mais rápida e o evento `loja_enriquecida` não é cobrado.
- **Monitorar uma loja concorrente?** Coloque a URL da loja em `urls` e agende a execução na Apify.
- **Acompanhar produtos específicos?** Cole as URLs dos produtos: cada URL vira no máximo uma linha.
- **Termo em inglês funciona**: `laptop` traz notebooks, `sneakers` traz tênis. Um nome de produto em português não é descartado.
- `vendidos` é **limite inferior**: `10mil+` significa pelo menos 10.000. Compare produtos pelo mesmo `vendidos_periodo`.

### Casos de uso

1. **Monitoramento de preço**: acompanhe preço e desconto de uma lista de produtos ou de uma loja ao longo do tempo.
2. **Benchmarking de concorrentes**: compare nota, avaliações e vendidos das lojas que aparecem no seu termo.
3. **Pesquisa de produto**: descubra faixa de preço (use `menor_preco` e `maior_preco`), origem do envio e lançamentos (`mais_recentes`) de um nicho.
4. **QA de catálogo e de marca**: veja como e por quem a sua marca é vendida na Shopee, e a que preço.
5. **Due diligence de fornecedor**: confira reputação (nota e avaliações) de uma loja antes de negociar.
6. **Pesquisa de vendedores**: monte uma lista de lojas ativas num segmento, com o tamanho de cada uma medido em avaliações.

### Perguntas frequentes

**Por que muitos produtos vêm com `vendidos` nulo?**
A página de busca da Shopee não mostra vendidos para visitante sem login, em nenhuma das 6 ordenações (0 de 240 cards medidos). A página do produto também não: sem JavaScript ela traz só o nome. A fonte que o actor usa são os destaques da página da loja, que publicam vendidos para parte dos produtos dela. Numa busca de 60 produtos com a loja consultada, 18% a 21% vieram com vendidos. Quando não há número, `vendidos_motivo_nulo` explica o caso. O actor não estima.

**Quantos produtos consigo por palavra-chave?**
Medido em 14/09/2026: 251 a 338 únicos por termo com as 6 ordenações e 3 páginas cada, e 64 a 138 só com relevância e 10 páginas. O número varia com o termo e de um dia para o outro, porque a Shopee repete produtos entre páginas em proporções diferentes. Para ir além, use mais termos.

**Busquei um termo e veio zero produto. Quebrou?**
Provavelmente não. A Shopee responde a termo inexistente com uma vitrine de recomendação genérica, e o actor reconhece essa troca pelo painel de filtros da página. O `OUTPUT` traz `sem_resultado_real: true` e nada é cobrado. Bloqueio é outra coisa: a página é pedida de novo com outro IP e, se ainda assim falhar, o resumo mostra a falha e a execução não finge que o termo não tem resultado.

**O `preco` é o preço no cartão ou no Pix?**
É o preço que o card exibe. Quando a Shopee o mostra como "no Pix", `preco_no_pix` vem `true`: pagando de outra forma o valor pode ser maior, e o card não mostra o preço riscado. Quando o card mostra preço e preço riscado, `preco_no_pix` vem `false`.

**Colei a URL de um produto. O que vem?**
Só aquele produto, com a loja anexada se `enriquecerLoja` estiver ligado. Se o produto não existe, nada é entregue nem cobrado e o resumo diz `produto nao encontrado na Shopee`.

**Por que uma loja vem só com o nome, sem nota?**
Algumas lojas, em geral de vendedores internacionais, não têm página pública renderizada para visitante sem JavaScript. O actor pega o nome pela busca da loja e deixa nota e avaliações nulas, com o motivo. Essa loja não é cobrada como `loja_enriquecida`.

### Preço

Pague por resultado, com dois eventos:

| Evento | Quando é cobrado | Preço |
|---|---|---|
| `produto` | produto entregue no dataset | US$ 0,005 |
| `loja_enriquecida` | loja resolvida com nome, nota e avaliações e anexada a produto entregue, 1 vez por loja por execução | US$ 0,002 |

Exemplo: 50 produtos de 35 lojas = 50 × 0,005 + 35 × 0,002 = **US$ 0,32**.

Não é cobrado: busca sem resultado real, loja ou produto não encontrado, entrada inválida, produto barrado na validação, lote retido por `LAYOUT_SUSPEITO`, produto repetido na mesma execução, e loja que veio só com o nome, passou do `maxLojas` ou falhou.

### Actors relacionados

- [📉 Monitor de Preço Mercado Livre — Alerta de Queda e Estoque](https://apify.com/paulovitor18/mercado-livre-monitor-preco)
- [Amazon Brasil Sellers com CNPJ — Leads B2B e Receita Federal](https://apify.com/paulovitor18/amazon-brasil-vendedores-cnpj)
- [Consulta CNPJ em Lote — Dados da Receita Federal](https://apify.com/paulovitor18/cnpj-bulk-lookup)
- [Reclame Aqui Scraper — Reputação de Empresas BR](https://apify.com/paulovitor18/reclameaqui-scraper)

### Histórico de versões

- **0.0 (14/09/2026)**: primeira versão. Busca por palavra-chave em 6 ordenações, loja e produto por URL, loja anexada com cache e teto, vendidos com período e procedência, preço no Pix sinalizado, detecção de busca sem resultado real, validação antes de cobrar e reserva residencial em bloqueio.

### Contato

Encontrou um produto com campo errado ou uma URL da Shopee que não é aceita? Abra uma issue na aba **Issues** deste actor com a URL e o ID da execução.

***

**In English:** Shopee Brazil scraper (shopee.com.br) for keyword search, shop pages and product URLs. It returns price in BRL (flagging Pix prices), discount, rating, ship-from location, sold count labeled as all-time or monthly when Shopee publishes it, and the seller shop's name, rating and review count. Search results are collected across 6 sort orders without duplicates. Searches with no real result return zero items and are not charged. It is pay-per-result, needs no login and no browser, and its output keys are in Portuguese. Built for Shopee BR price monitoring, competitor and seller research.

# Actor input Schema

## `palavrasChave` (type: `array`):

Termos buscados na shopee.com.br, um por linha (ex.: air fryer). Produto repetido entre páginas ou entre buscas sai uma vez só.

## `urls` (type: `array`):

URLs de busca (https://shopee.com.br/search?keyword=...), de loja (https://shopee.com.br/shop/<id>, lista a vitrine da loja) ou de produto (entrega só aquele produto). URL de outro site é recusada sem consulta e sem cobrança.

## `maxItensPorBusca` (type: `integer`):

Produtos únicos por palavra-chave ou loja pedida. Volume medido em 14/09/2026: com as 6 ordenações e 3 páginas cada, 251 a 338 produtos únicos por termo; só com relevância e até 10 páginas, 64 a 138. A busca para assim que atinge este máximo.

## `maxPaginasPorBusca` (type: `integer`):

Páginas por ordenação (cada página traz até 40 cards). Dentro de uma ordenação, a busca passa para a próxima quando uma página traz menos de 5 produtos novos, porque a Shopee passa a repetir.

## `ordenacoes` (type: `array`):

A Shopee devolve produtos diferentes em cada ordenação; o actor percorre na ordem abaixo, sem repetir produto, só até completar o máximo por busca. Volume medido em 14/09/2026: com as 6 ordenações e 3 páginas cada, 251 a 338 produtos únicos por termo; só com relevância e até 10 páginas, 64 a 138.

## `enriquecerLoja` (type: `boolean`):

Anexa nome, nota e número de avaliações da loja, e vendidos quando o produto está entre os destaques dela. Cobra o evento loja\_enriquecida 1 vez por loja resolvida com nota e avaliações e anexada a um produto entregue. Custa 1 a 2 páginas por loja nova (lojas repetidas saem do cache). Desligue para receber só os dados do produto.

## `maxLojas` (type: `integer`):

Teto de lojas novas consultadas para enriquecer produtos de busca. 40 cobre uma busca de 50 produtos (cerca de 35 lojas distintas). Produto de loja além do limite sai com os campos de loja nulos e o motivo. Lojas pedidas por URL não contam neste limite.

## `proxyGrupo` (type: `string`):

DATACENTER funcionou sem bloqueio nas medições. RESIDENTIAL (Brasil) é mais lento e fica como alternativa.

## `reservaResidencial` (type: `boolean`):

Se uma página for bloqueada em todas as tentativas por datacenter, tenta mais uma vez por um IP residencial do Brasil antes de desistir.

## `tentativas` (type: `integer`):

Em bloqueio ou erro de rede a página é pedida de novo com outro IP, com espera crescente (1,5 s, 3 s, 6 s).

## `timeoutMs` (type: `integer`):

Limite por requisição (cabeçalho e corpo).

## `salvarHtmlBruto` (type: `boolean`):

Grava cada página baixada no key-value store da execução.

## Actor input object example

```json
{
  "palavrasChave": [
    "air fryer"
  ],
  "urls": [],
  "maxItensPorBusca": 20,
  "maxPaginasPorBusca": 5,
  "ordenacoes": [
    "relevancia",
    "mais_vendidos",
    "populares",
    "mais_recentes",
    "menor_preco",
    "maior_preco"
  ],
  "enriquecerLoja": true,
  "maxLojas": 40,
  "proxyGrupo": "DATACENTER",
  "reservaResidencial": true,
  "tentativas": 3,
  "timeoutMs": 30000,
  "salvarHtmlBruto": false
}
```

# Actor output Schema

## `dados` (type: `string`):

Produtos emitidos nesta execução, no formato descrito em dataset\_schema.json.

## `resumo` (type: `string`):

Contadores, buscas sem resultado real, lojas não encontradas e falhas.

# 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 = {
    "palavrasChave": [
        "air fryer"
    ],
    "maxItensPorBusca": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("paulovitor18/shopee-brasil-produtos").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 = {
    "palavrasChave": ["air fryer"],
    "maxItensPorBusca": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("paulovitor18/shopee-brasil-produtos").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 '{
  "palavrasChave": [
    "air fryer"
  ],
  "maxItensPorBusca": 20
}' |
apify call paulovitor18/shopee-brasil-produtos --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,paulovitor18/shopee-brasil-produtos"
        }
    }
}
```

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/iIjzABPCf9cxdgzyS/builds/AYgZ6g281YnXDnhMK/openapi.json