Shopdora — Shopee Product Selection & Keyword Research Tool

This skill should be used when the user wants to perform data analysis on Shopee platforms, including: keyword research, product discovery & search.

Shopdora - Shopee Product Research & Keyword Analytics Tool

Overview

Leverage the Shopdora OpenAPI to perform cross-border ecommerce data analysis on Shopee across all supported sites. Capabilities include keyword research, product discovery, review scraping, category browsing, and balance queries.

Important prerequisite: Using this skill requires registering an account on the Shopdora website and activating the API service. This is a paid service — contact the official customer service (WeCom) on the website for pricing details.

---

Typical Use Cases

You can ask questions in plain English, for example:

• "What are the hottest products in the beauty category on Shopee Thailand?"
• "Show me trending keywords for phone cases on Shopee Singapore"
• "How much quota is left on my account?"
• "Get reviews for product ID xxx from Shopee Taiwan"
• "What categories are available on Shopee Malaysia?"

---

Prerequisites: Credential Setup

Check Configuration

Before making any API call, check if the local credential file ~/.shopdora/config.json exists:

bash

cat ~/.shopdora/config.json 2>/dev/null

First-Time Setup — Guide the User

If the config file doesn't exist, reply to the user:

This is a paid service. Please visit https://www.shopdora.com and contact official customer service to get your token. Once you have your clientId and clientSecret, share them with me and I'll set it up.

After receiving the credentials, create the config file:

bash

mkdir -p ~/.shopdora

Then write the JSON config with the user-provided clientId and clientSecret.

Config File Format

json

{
  "clientId": "std_xxxxxxxx",
  "clientSecret": "your_secret_here"
}

---

Site Name Mapping

Users may refer to sites by name rather than code. Auto-convert using this mapping:

User might say	Maps to site code
Singapore, sg	sg
Taiwan, tw	tw
Malaysia, my	my
Philippines, ph	ph
Thailand, th	th
Vietnam, vn	vn
Indonesia, id	id
Brazil, br	br
Mexico, mx	mx

If the user hasn't specified a site, ask which site they want to query.

---

Core Workflow

Standard call sequence: Regardless of the user's request, always follow this order:

1. Check credentials → Read ~/.shopdora/config.json
2. Get token → Check if ~/.shopdora/token.json is valid; re-acquire if expired
3. Check local cache → Serve from cache for identical requests within 24 hours (no cost — see "Local Cache" section below)
4. Confirm key parameters → Before calling any paid endpoint, confirm site, keyword, time range, etc. with the user (see "Pre-Call Confirmation" section below)
5. Optional: Query balance → Optionally check balance to confirm sufficient quota before execution
6. Execute request → Call the appropriate endpoint based on user intent (keyword/product/review/category)
7. Cache result & display → Write to cache on success, present results in a table or structured format

---

Ask When Information is Missing

When encountering unclear or missing information, you MUST ask the user before proceeding — never infer:

Missing info	Alternative behavior example
No site specified	Ask: "Which Shopee site would you like to query?"
Vague keyword	Ask: "Could you specify the category or product keyword?"
Ambiguous time range (e.g., "recent" / "hot")	Ask: "Would you prefer the last 30 days or a specific month?"

---

Pre-Call Confirmation (Prevent Wasted Quota)

Before calling any paid endpoint (keyword, product, review), you MUST confirm key parameters with the user to avoid wasting quota due to incorrect parameters.

Confirmation example:

About to call the Keyword Research API (charged):

• Site: Singapore (sg)
• Keyword: phone case
• Search volume range: 1,000 ~ 50,000
• Sort by: Search volume (descending)

Proceed?

Only call the API after the user confirms.

---

Failure / Empty Result Handling (NO Auto-Retry)

When a paid endpoint returns a failure or empty result, the following actions are strictly forbidden:

• ❌ Automatically changing keywords and retrying
• ❌ Automatically paginating to fetch more data
• ❌ Automatically modifying site, price range, time range, or any parameter and retrying
• ❌ Automatically changing sort order and retrying

Correct approach:

• Empty result → Inform the user that no data was found under the current conditions, and suggest they adjust the criteria and let you know
• Failure (code ≠ 0000) → Handle per the error code table; only auto-retry on token expiration (9990)
• User requests next page or more data → First inform them of the additional quota cost, then proceed only after confirmation

For example, when the user says "show next page":

Fetching the next page will consume 1 quota (X remaining). Continue?

---

Local Cache (24h)

To reduce redundant quota consumption, all successful paid endpoint responses are cached locally.

Cache location: ~/.shopdora/cache/

Cache file naming: {endpoint}_{site}_{paramMD5}.json

• Examples: keyword_sg_a1b2c3d4.json, product_th_e5f6g7h8.json

Cache logic:

1. Before calling the API, compute the MD5 of the request parameters (serialize site + all query params as a JSON string, then hash)
2. Check if a corresponding file exists under ~/.shopdora/cache/
3. If exists and modified within 24 hours → Read from cache, inform user "(from cache, X hours ago)", skip API call
4. If not found or expired → Call API, write/update cache file on success
5. Balance queries (free, not rate-limited) and token acquisition (free) are NOT cached

---

Workflow 1: Get Access Token

A valid access token is required before any paid API calls.

Token persistence mechanism:

The token is stored in ~/.shopdora/token.json:

json

{
  "accessToken": "a1b2c3d4e5f6...",
  "tokenType": "Bearer",
  "expiresIn": 2678400,
  "obtainedAt": 1753718400
}

Token acquisition and validation flow:

1. First, attempt to read ~/.shopdora/token.json
2. If the file exists, check if obtainedAt + expiresIn > current timestamp; use directly if valid
3. If the file doesn't exist or has expired, read credentials from ~/.shopdora/config.json and call the token endpoint
4. Write the new token and acquisition time to ~/.shopdora/token.json
5. All subsequent API requests read accessToken from token.json

API call:

bash

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/token' \
  -H 'Content-Type: application/json' \
  -d '{"clientId":"<read from config>","clientSecret":"<read from config>"}'

Token renewal rules:

• Token is valid for ~31 days; re-acquire before expiration
• When any API returns 9990, automatically delete token.json, re-acquire the token, and retry the original request
• Check the tokenExpiresIn field from /standard/queryBalance for the precise expiration time

---

Workflow 2: Query Balance

Proactively query when the user asks for balance, before bulk calls, or at the start of a session.

API call:

bash

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/queryBalance' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>'

Result display format (must clearly present the following):

text

📊 Account Info
- Client Name: {clientName}
- Account Status: {accountStatus}
- Token Expires: {tokenExpiresIn}

💰 Quota Usage
- Period: {periodStart} ~ {periodEnd}
- Used / Limit: {quotaUsed} / {quotaLimit} ({quotaRemaining} remaining)

⚡ Rate Limit
- Per-minute limit: {rateLimitPerMinute} calls/min
- Used this minute: {rateLimitUsedThisMinute} calls

---

Workflow 3: Keyword Research

Use when the user wants to find trending search terms for a category or product.

Pre-call check: Check 24h cache first, then confirm parameters (site, keyword, filters) with the user. Only call API after confirmation. Do NOT auto-retry on failure or empty results.

Required params: site Common optional params: keyword, cateIds, searchVolume, sortBy

API call:

First determine the site code using the site name mapping, confirm the user's filter criteria, then call:

bash

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/keyword/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
    "site": "<site>",
    "keyword": "<keyword>",
    "searchVolume": {"min": <min>, "max": <max>},
    "sortBy": "<sortBy>",
    "orderBy": 1,
    "pageNum": 1,
    "pageSize": 20
  }'

Result display: Present keywords in a table with key metrics: searchVolume, searchVolumeIncRate, productNum, avgPrice, avgRating. If there are many results, inform the user that more pages are available (each additional page costs 1 quota).

---

Workflow 4: Product Discovery

Use when the user wants to discover and analyze trending products or competitors on Shopee.

Pre-call check: Check 24h cache first, then confirm parameters (site, keyword/category, price range, time range) with the user. Only call API after confirmation. Do NOT auto-retry on failure or empty results.

Required params: site, month Common optional params: keyword, cateIds, price, salesM, shelfTimeRange, sortBy

month parameter:

• 30 → Last 30 days view (most common)
• 202603 → Specific month view

price parameter:

• Value = actual price × 100000, e.g. $9.90 → 990000

API call:

bash

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/product/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
    "site": "<site>",
    "month": 30,
    "keyword": "<keyword>",
    "sortBy": "salesM",
    "orderBy": 1,
    "pageNum": 1,
    "pageSize": 20
  }'

Result display:

• Present products in a table with: name, price (divide by 100000 for local currency), salesM, salesGrowthRateM, cateRank, shopType, etc.
• price fields must be divided by 100000 to display as local currency
• salesGrowthRateM must be divided by 100 to display as percentage
• ratingScore must be divided by 10 to display as stars
• shopType conversion: 0 → Regular Shop, 1 → Preferred Shop, 2 → MALL

---

Workflow 5: Review Scraping & Analysis

Use when the user wants to view buyer reviews for a product or analyze customer feedback.

Pre-call check: Check 24h cache first, then confirm parameters (site, shopId, itemId) with the user. Only call API after confirmation. Do NOT auto-retry on failure or empty results.

Required params: site, shopId, itemId, limit, offset

API call:

bash

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/comment/get' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{
    "site": "<site>",
    "shopId": <shopId>,
    "itemId": <itemId>,
    "limit": 20,
    "offset": 0
  }'

Pagination logic:

• Max 20 per page, offset starts at 0, max 3000
• Read response data.data.has_more; if true, offset += limit to fetch next page
• When user requests "more", first inform them of the additional quota cost before fetching

Result display:

• First show review summary: total reviews, overall star rating, star distribution
• List each review: star rating, username, content (truncated to 150 chars), likes, whether it has images
• ctime is Unix seconds — convert to readable time
• If the review has template_tags, display tag info

---

Workflow 6: Category Browsing

Use when the user needs to browse a site's product category tree.

API call:

bash

curl -s -X POST 'https://openapi.shopdora.cn/openapi/standard/cate/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -d '{"site":"<site>","cateId":0}'

Note: Response data is a JSON string — you must JSON.parse before displaying.

Result display: Present the category tree with indentation, marking leaf nodes.

---

Site Code Quick Reference

Code	Site	Code	Site
sg	Singapore	vn	Vietnam
tw	Taiwan, China	id	Indonesia
my	Malaysia	br	Brazil
ph	Philippines	mx	Mexico
th	Thailand

---

Error Handling

code	Description	Action
0000	Success	Display results normally
0001	Invalid parameter	Check and correct request parameters, then retry
9990	Token invalid	Delete token.json, re-acquire token, retry original request
9992	IP not whitelisted	Inform user that current IP is not whitelisted; contact platform
9993	Rate limited	Wait a few seconds and retry automatically, up to 3 times
9997	Quota exhausted	Inform user that quota is used up; suggest waiting for next period or contacting support for expansion
9999	System busy	Wait 3 seconds and retry, up to 2 times

---

Important Reminders

1. Paid service: Keyword research, product discovery, and review scraping each consume 1 quota per successful call (returning non-empty data). Balance queries and category browsing are free.
2. Pre-call confirmation: Before any paid API call, you MUST confirm key parameters (site, keyword, time range, etc.) with the user — never auto-infer.
3. No auto-retry: On failure or empty results, DO NOT automatically change keywords, paginate, or modify parameters to retry. Only auto-retry on token expiration (9990).
4. Notify on pagination / additional retrieval: When the user requests next page or more data, first inform them of the additional quota cost before proceeding.
5. 24h local cache: All successful paid endpoint responses are cached in ~/.shopdora/cache/. Identical requests within 24 hours are served from cache without consuming quota.
6. Quota awareness: After each paid API call, inform the user of the consumption and remaining quota.
7. Price fields: All price fields from product/search must be divided by 100000 to show as local currency.
8. Data freshness: Keyword data is not real-time; it depends on the platform's refresh cycle.
9. Pagination limit: Review offset is capped at 3000.

---

Reference

For detailed API field definitions, parameter boundaries, and complete response JSON structures, load references/api_docs.md using the Read tool.