nexscope-ai/nexscope-ecommerce-skills / ecommerce-shopee-product-detail
ecommerce.shopee-product-detail
VerifiedRetrieve the current public details of one Shopee listing from a supported product URL, including price, discount, sales, stock, variants, media, brand, category, shop, and rating data. Use when a user provides a Shopee product URL and asks for listing details, SKU variants, inventory, pricing, or competitor-page analysis. Do not use for keyword search, historical trends, reviews, or seller-account operations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.4 KB |
| manifest.json | config | 448 B |
| references/api.md | markdown | 5.7 KB |
| references/testing.md | markdown | 3.9 KB |
| scripts/shopee_product_detail.py | script | 9.9 KB |
references/api.md
View on GitHub## Nexscope billing
The migrated Skill does not inherit the source platform's point value. This operation consumes Nexscope credits. Preserve X-Cost-Token and X-Cost-Credit from the HTTP response headers as server-reported billing metadata, and preserve X-Kong-Trace-Id for diagnostics.
# Shopee Product Detail API
## Request
- Endpoint: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/shopee/product/detail`
- Method: `POST`
- Content type: `application/json`
- Authentication: `Authorization: Bearer ${NEXSCOPE_API_KEY}`
- Timeout: 150 seconds
- Forwarded tracing headers: `SESSION_ID`, `MESSAGE_ID`, `MODE_ID`, and `APP_NAME` when present
### Body
| Parameter | Type | Required | Description |
|---|---|---:|---|
| `productUrl` | string | yes | Shopee HTTPS listing URL whose path ends in `-i.<numeric shopId>.<numeric itemId>` |
Supported hosts are `shopee.sg`, `shopee.co.id`, `shopee.com.my`, `shopee.ph`, `shopee.co.th`, `shopee.tw`, `shopee.vn`, and `shopee.com.br`. Ports are omitted or must be `443`.
Only `productUrl` is public input. The service infers the marketplace from the host and must return exactly the product identified by the URL.
```json
{
"productUrl": "https://shopee.sg/example-i.9641401.29691169956"
}
```
## Nexscope response envelope
These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.
`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.
Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.
```json
{"code":0,"msg":null,"data":{}}
```
Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.
## Response
| Field | Type | Description |
|---|---|---|
| `data` | array | Exactly one product on success |
| `total` | integer | `1` on success |
| `costToken` | integer | Legacy business-body token field; do not use it instead of the `X-Cost-Token` response header |
| `type` | string | Rendering type, normally `tableListWorkbenches` |
| `columns` | array | Rendering column definitions |
Common product fields:
| Group | Fields |
|---|---|
| Identity | `itemId`, `shopId`, `url`, `name`, `brand`, `categoryId`, `categoryBreadcrumb` |
| Media | `image`, `images`, `videos` |
| Pricing | `price`, `priceBeforeDiscount`, `priceMin`, `priceMax`, `discountPercent`, `currency` |
| Demand | `sold`, `soldDisplayed`, `rating`, `ratingCount`, `ratingDistribution`, `likedCount` |
| Inventory | `stock`, `tierVariations`, `models` |
| Shop | `shopName`, `shopRating`, `shopLocation`, `isMall`, `isOfficialShop`, `isShopeeVerified`, `shop` |
| Content | `description`, `attributes`, category data, availability, and condition when supplied |
Less-common top-level product fields are preserved. Fields may be absent or `null`, and some marketplaces return lighter records.
## Errors and invariants
| Condition | Expected handling |
|---|---|
| Missing or malformed `productUrl` | Reject before network access in the client; the gateway also returns a business error |
| Unsupported host or URL form | Use a supported direct listing URL; do not silently rewrite it |
| Removed or market-mismatched listing | Report the gateway error; do not automatically probe other marketplaces |
| Returned IDs differ from the URL | Treat the response as invalid and do not present the wrong product |
| More or fewer than one valid product | Treat as an upstream error |
| HTTP 401 | Check `NEXSCOPE_API_KEY` and authorization |
| HTTP 402 | Report insufficient credits |
| Timeout or 5xx | Report the failure; do not automatically repeat a paid call |
## curl
```bash
curl -X POST "${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/shopee/product/detail" \
-H "Authorization: Bearer ${NEXSCOPE_API_KEY}" \
-H "Content-Type: application/json" \
-H "SESSION_ID: ${SESSION_ID:-}" \
-H "MESSAGE_ID: ${MESSAGE_ID:-}" \
-H "MODE_ID: ${MODE_ID:-}" \
-H "APP_NAME: ${APP_NAME:-}" \
-d '{"productUrl":"https://shopee.sg/example-i.9641401.29691169956"}'
```
## API Key request rate and retries
All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.
HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |