Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-shopee-product-detail

ecommerce.shopee-product-detail

Verified

Retrieve 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.

FileKindSize
SKILL.mdskill md5.4 KB
manifest.jsonconfig448 B
references/api.mdmarkdown5.7 KB
references/testing.mdmarkdown3.9 KB
scripts/shopee_product_detail.pyscript9.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.
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 implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall