Shopee Brazil Search Skill

Search and analyze products on Shopee Brazil (shopee.com.br) via CLI using Camoufox stealth browser.

Prerequisites

IMPORTANT: Before running any command, check if the venv exists. If it does not, create it and install all dependencies:

if [ ! -d "<SKILL_DIR>/.venv" ]; then
  cd <SKILL_DIR>
  python3 -m venv .venv
  .venv/bin/pip install "camoufox[geoip]" playwright beautifulsoup4 lxml browser-cookie3
  .venv/bin/python3 -m camoufox fetch
fi

PYTHON=<SKILL_DIR>/.venv/bin/python3

Quick Reference

Command	Description
`search -q QUERY`	Search products by keyword
`search -q QUERY --sort sales`	Search sorted by best sales
`details --url URL`	Get full details of a product
`categories`	List main product categories
`cookies`	Extract & verify Shopee cookies from browser
`cookies --export FILE`	Export cookies to JSON file

Headless mode works by default — no --visible flag needed.

macOS: Requires XQuartz (provides Xvfb virtual display). Install once with brew install --cask xquartz, then log out and back in. The skill auto-manages Xvfb.
Linux: Works out of the box via Xvfb (headless="virtual" in Camoufox).
Fallback: If XQuartz is not installed on macOS, use --visible to show the browser window.

Script Location

<SKILL_DIR>/scripts/shopee.py

Commands

1. Search Products

$PYTHON scripts/shopee.py search -q "iphone 15" --limit 5

Arguments:

Flag	Short	Description	Default
`--query`	`-q`	Search term	(required)
`--page`		Page number (0-based)	0
`--min-price`		Minimum price in BRL	(none)
`--max-price`		Maximum price in BRL	(none)
`--sort`		Sort: `relevance`, `sales`, `price-asc`, `price-desc`, `newest`	relevance
`--limit`		Max results to return	20
`--visible`		Show browser window (fallback if headless fails)	false

Search with filters:

# Search phones with price range
$PYTHON scripts/shopee.py search -q "iphone" --min-price 2000 --max-price 5000

# Search by best sales
$PYTHON scripts/shopee.py search -q "notebook" --sort sales

# Page 2 of results (0-indexed)
$PYTHON scripts/shopee.py search -q "kindle" --page 1

Output structure:

{
  "success": true,
  "query": "iphone 15",
  "url": "https://shopee.com.br/search?keyword=iphone+15&page=0&sortBy=relevancy",
  "status": 200,
  "page": 0,
  "sort": "relevance",
  "results_count": 5,
  "blocked": false,
  "source": "api",
  "results": [
    {
      "item_id": "12345678901",
      "shop_id": "123456789",
      "title": "Apple iPhone 15 128GB - Preto",
      "url": "https://shopee.com.br/product/123456789/12345678901",
      "price": "R$ 4.499,00",
      "price_value": 4499.0,
      "original_price": "R$ 5.999,00",
      "discount": "25%",
      "rating": "4.9",
      "sold": "1,2mil vendidos",
      "image": "https://down-br.img.susercontent.com/file/..."
    }
  ]
}

Key fields:

source: "api" (data from Shopee's internal API — most reliable) or "html" (fallback DOM parsing)
blocked: true if Shopee served a CAPTCHA page
price_value: numeric float for programmatic comparison

2. Get Product Details

# By URL
$PYTHON scripts/shopee.py details --url "https://shopee.com.br/product/123456789/12345678901"

Output structure:

{
  "success": true,
  "source": "api",
  "blocked": false,
  "item_id": "12345678901",
  "shop_id": "123456789",
  "title": "Apple iPhone 15 128GB - Preto",
  "price": "R$ 4.499,00",
  "price_value": 4499.0,
  "rating": "4.9",
  "reviews_count": "1234",
  "stock": "50 em estoque",
  "seller": "Apple Store Oficial",
  "images": ["https://down-br.img.susercontent.com/file/..."],
  "description": "Full product description text...",
  "specs": {
    "Marca": "Apple",
    "Modelo": "iPhone 15",
    "Armazenamento": "128 GB"
  }
}

3. List Categories

$PYTHON scripts/shopee.py categories

Returns the main category list from Shopee Brazil:

{
  "success": true,
  "count": 15,
  "categories": [
    {"id": "100629", "name": "Celulares e Dispositivos"},
    {"id": "100644", "name": "Computadores e Acessórios"},
    {"id": "100633", "name": "Eletrônicos"}
  ]
}

4. Extract & Verify Cookies

Automatically extracts Shopee cookies from the user's browser (Chromium, Chrome, Brave, Firefox, Edge). Cookies improve scraping success rate by appearing as a logged-in user.

# Auto-detect browser and verify authentication
$PYTHON scripts/shopee.py cookies

# Use a specific browser
$PYTHON scripts/shopee.py cookies --browser brave

# Export cookies to a file
$PYTHON scripts/shopee.py cookies --export ~/shopee-cookies.json

Output:

{
  "success": true,
  "browser": "chromium",
  "cookie_count": 45,
  "authenticated": true,
  "cache_file": "<SKILL_DIR>/.cookies_cache.json"
}

Cookie priority chain:

--cookies-file FILE (explicit file path)
Cached cookies (auto-saved from last extraction)
Auto-extract from browser (tries chromium → chrome → brave → firefox → edge → opera)

Important: The user must have visited shopee.com.br in their browser for cookies to be available. Being logged in provides better results (less CAPTCHA).

Common Workflows

Price comparison

# Search and compare prices
$PYTHON scripts/shopee.py search -q "macbook air m3" --sort price-asc --limit 10

Product research

# Get details to evaluate a product
$PYTHON scripts/shopee.py details --url "https://shopee.com.br/product/..."

Deal hunting

# Find best sellers
$PYTHON scripts/shopee.py search -q "fone bluetooth" --sort sales

Technical Notes

Uses Camoufox (stealth Firefox via Playwright) with humanize=True for anti-bot bypass
Data is extracted by intercepting Shopee's internal REST APIs (/api/v4/search/search_items, /api/v4/pdp/get_pc) during page navigation — NOT by parsing rendered HTML (Shopee is a React SPA with no server-side rendered data)
Falls back to HTML DOM parsing if API interception fails
Headless mode works by default on macOS (via XQuartz/Xvfb) and Linux (via native Xvfb). Use --visible only as a fallback if headless fails.
Locale is set to pt-BR for proper Shopee.com.br content
Retry logic: 3 retries with exponential delay on failures or CAPTCHA pages
CAPTCHA detection: automatically detects Shopee bot-check pages in responses
Rate limiting: Shopee aggressively rate-limits IPs. Space commands at least 5-10 seconds apart. After 5+ rapid requests, expect a ~2 minute cooldown before CAPTCHA clears
Cookies improve reliability — extract them with cookies command first
All output is JSON to stdout, errors to stderr, exit code 0/1
Price values are parsed as floats (e.g., "R$ 4.499,00" → 4499.0)
The source field indicates whether data came from API interception ("api") or HTML fallback ("html")

Error Handling

Errors return JSON with an error field to stderr:

{"success": false, "error": "Fetch failed for https://...", "details": "Timeout"}

If Shopee serves a CAPTCHA page, the response includes "blocked": true:

{"success": true, "blocked": true, "results_count": 0, "results": []}

Tips to avoid CAPTCHA:

Extract cookies first: $PYTHON scripts/shopee.py cookies
Space requests at least 5-10 seconds apart
Don't make more than 5 requests in quick succession — wait ~2 minutes if you hit CAPTCHA
Being logged in to Shopee in your browser helps (cookies are auto-extracted)
If headless keeps getting blocked, use --visible as fallback

Exit code 1 on errors, 0 on success.