tail-fin-shopee 0.7.8

Shopee adapter for tail-fin: account info, search (browser-only), product detail. Multi-region (TW/SG/MY/...).
Documentation

tail-fin-shopee

Shopee marketplace adapter for tail-fin. Multi-region (Taiwan, Singapore, Malaysia, Indonesia, Vietnam, Philippines, Thailand, Brazil) — region-qualified Site::id() (e.g. "shopee-tw").

Status

Shopee's anti-bot infrastructure (af-ac-enc-dat / af-ac-sz request signatures) blocks most /api/v4/* endpoints from a plain HTTP client. The adapter ships two complementary modes:

Command Mode Auth Notes
me HTTP Cookie file /api/v4/account/basic/get_account_info — works with cookies alone
search Mode A (attached Chrome) Logged-in tab /api/v4/search/search_items — supports --page N pagination (60 items / page)
detail Mode A (attached Chrome) Logged-in tab /api/v4/pdp/get_pc — full product detail (description, full image gallery, variant models, ratings)
related Mode A (attached Chrome) Logged-in tab /api/v4/pdp/hot_sales + /api/v4/recommend/product_detail_page — bestsellers + personalised "you may also like"
cart Mode A (attached Chrome) Logged-in tab /api/v4/cart/mini — preview of 5 most-recent cart items + total / unique counts
discover Mode A (attached Chrome) Logged-in tab /api/v4/homepage/get_daily_discover + flash_sale/flash_sale_get_items + homepage/mall_shops — 3 endpoints from one homepage navigation
categories Mode A (attached Chrome) Logged-in tab /api/v4/pages/get_homepage_category_list — top-level category tree (24 categories on shopee.tw)
category Mode A (attached Chrome) Logged-in tab /api/v4/search/search_items?fe_categoryids=…&scenario=PAGE_CATEGORY (sort-click triggered — page is SSR'd, no XHR fires on bare load) + get_fe_category_detail — items in a leaf sub-category (60 items, sorted newest-first) + metadata. Two-arg: <parent_catid> <leaf_catid>.
shop Mode A (attached Chrome) Logged-in tab /api/v4/promotion/get_shop_info — seller info (name / address / item_count / follower_count / rating breakdown). Doesn't fire on Shopee-direct listings — see docs
reviews Mode A (attached Chrome) Logged-in tab /api/v2/item/get_ratings (note: v2) — product reviews + summary; pagination via has_more flag
shop-items Mode A (attached Chrome) Logged-in tab /api/v4/shop/rcmd_items (POST) or shop/search_items (GET) — paginated list of a shop's items; 30 per page
search-user Mode A (attached Chrome) Logged-in tab /api/v4/search/search_user — find shops by keyword (single most-relevant result by default)
homepage Mode A (attached Chrome) Logged-in tab Combined cart + discover + categories in one homepage navigation; saves ~60s vs individual calls

Orders are next — same Mode A capture pattern.

Empirically verified (2026-04-29): wreq with Chrome 145 emulation (the same trick tail-fin-sa uses to bypass PerimeterX) does not solve Shopee's 403. Every protected endpoint returns {is_login: true, error: 90309999} — Shopee's WAF accepts the cookies and knows the user is logged in; it's blocking on the missing signature, not on TLS fingerprint. Fresh stealth Chromium also fails across all 4 variants (headless cold/warm, headed cold/warm) — Shopee scores fingerprint cleanliness + device-cookie binding too aggressively. See ~/.claude/.../memory/shopee_antibot_signature.md for the full probe. Mode A (attach to user's real Chrome) is the only viable path for search/cart/etc., same pattern as Reddit / YouTube / Coupang / Spotify.

Auth

Cookies are required for all endpoints. Export from a logged-in browser session into Netscape format at:

~/.tail-fin/shopee-tw-cookies.txt   # Taiwan
~/.tail-fin/shopee-sg-cookies.txt   # Singapore
~/.tail-fin/shopee-my-cookies.txt   # Malaysia
…

The critical cookies for auth are SPC_ST, SPC_EC, SPC_T_ID, SPC_T_IV, SPC_U, SPC_F, SPC_SI, csrftoken. Shopee rotates SPC_ST / SPC_EC / SPC_T_* aggressively (multi-day TTL); re-export when 401s start.

Usage

# Account info (cookie HTTP)
tail-fin --cookies auto shopee me
tail-fin --cookies ~/.tail-fin/shopee-sg-cookies.txt shopee me  # explicit path

# Search (Mode A — needs Chrome at :9222 with a logged-in shopee tab)
tail-fin shopee search "iPhone"
tail-fin shopee search "noodles" --region sg --limit 10
tail-fin shopee search "iPhone" --page 2  # paginate (0-indexed)

# Product detail (uses shopid + itemid from a search result)
tail-fin shopee detail 188277742 43968123553

# Related / recommended products on the same PDP
tail-fin shopee related 188277742 43968123553

# Cart preview (5 most-recent items + total / unique counts)
tail-fin shopee cart

# Homepage discover surface — feeds + flash sale + mall shops
tail-fin shopee discover

# Top-level category tree
tail-fin shopee categories

# Browse a leaf sub-category — needs both parent + leaf catids
# (Shopee's URL router requires the full ancestor chain).
# Items come back sorted newest-first.
tail-fin shopee category 11040766 11042305     # Women's Apparel → Pants

# Shop / seller info (needs an itemid as PDP-navigation hint)
tail-fin shopee shop 1530245671 24546313093

# Product reviews
tail-fin shopee reviews 188277742 43968123553

# Shop catalogue (paginated, 30 items per page)
tail-fin shopee shop-items 109729156 --page 0

# Find shops by keyword
tail-fin shopee search-user "iPhone"

# Homepage bundle — cart + discover + categories in one navigation (~30s)
tail-fin shopee homepage

Mode A prereqs (one-time):

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.tail-fin/chrome-modea"

Then login + manually browse a few products in that Chrome before relying on search — a brand-new profile starts with zero trust score.

Full documentation: docs/sites/shopee.md

License

MIT