SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslinkfox-shopee-store-auth

linkfox-shopee-store-auth

General & other

View repository

Updated 10-15 23:59

About this skill

Shopee store authorization and management

OAuth authorization, authorized store list, and authorization status reading for Shopee Open Platform.Prerequisite dependency for downstream business(via /shopee/developerProxy to call the open API).

Shopee ERP and Advertising (AD) use different applications and Tokens, and authorization must be separated by capability.

Core Concepts

  • Dual applications：appType=erp(products/orders/logistics, etc., default) and appType=ad(on-platform advertising) are independent of each other; the same store can have two authorizations at the same time
  • Authorization flow: generate URL → user authorizes in browser → Shopee pushes Token → system stores in database by state save to database
  • Store identifier：shopId and merchantId either one alone is sufficient for locating; to determine whether authorization already exists, both must be matched shopId/merchantId + appType
  • shopName recommended to fill in: before calling authorize_url.py it is recommended to ask the user for an easily identifiable store name (not required by the API)
  • Authorization URL is valid for 1 hour: call again for each authorization authorize_url.py, do not cache the old address
  • Downstream store selection: business skill via developerProxy pass only shopId/merchantId + path；do notpass accessToken, and alsodo notpass in proxy appType(the server automatically routes by path:api/v2/ads/** → AD, other api/v2/** → ERP）
  • accessToken is valid for about 4 hours（expireIn usually 14400); after expiration, reauthorize according to the corresponding appType Reauthorize

Shopee authorization routing

  • Use appType=erp for product, order, logistics, and other ERP authorization.
  • Use appType=ad for Shopee Ads authorization.
  • Treat a missing or blank appType as erp.
  • Check authorization by both store identity and appType; one store may have separate ERP and AD records.
  • If the user needs both capabilities, obtain two fresh authorization URLs and explain that both authorizations must be completed.
  • Authorization URLs expire after one hour, so obtain a new URL for every authorization attempt.

When calling developerProxy, pass the Shopee API path plus shopId or merchantId. Do not pass appType or an access token. The service routes api/v2/ads/** through the AD application and all other api/v2/** paths through the ERP application.

Available scripts

Script Purpose
authorize_url.py Generate authorization URL (optional shopName / region / appType）
authorized_stores.py List authorized stores (including appType; the same store may have two)
store_tokens.py Check authorization/token for the specified applicationstatus(not a downstream token source; must include appType to distinguish)

For input parameters, response fields, and error codes, see references/api.md。

How to call

  • API endpoints：POST /shopee/{authorizeUrl|storeTokens|authorizedStores}(for complete parameters/responses/error codes, see references/api.md）
  • Python scripts：python scripts/<脚本名>.py '<JSON 参数>' [--inline](for available scripts, see above)
  • Cost constraints: this tool consumes compute; failures/empty results must not automatically trigger repeated trials; if further retrieval is needed, first explain to the user that additional consumption will be incurred.

Output strategy (default script behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json（<cwd> is the working directory when the script is executed, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated by user task;Writing to /tmp is prohibited, if the current directory is not writable, an error is reported)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts, length of the largest list field + first 3 samples)
  • Add --inline Force full output to stdout (also saved to disk)

Data reading suggestions: first check the summary to determine whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding putting the entire JSON into the context.

Resolve authentication and compute resource issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situations

  • API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute resources or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or similar meaning.

Supported regions

cn(China cross-border, default) / global(global authorization page) / br(Brazil). Default cn。

Usage Scenarios

1. Newly authorized store (ERP, default)

  1. Suggest asking the user for shopName(for later identification; API not required)
  2. Confirm region(default cn; global site global, Brazil br）
  3. call authorize_url.py, pass appType=erp(or do not pass it; the server defaults to erp) → open it for the user in the browser (security warning: to ensure store security, be sure to open this link in the secure network environment where the store is operated daily. It is strongly recommended to use a professional anti-association browser such as Ziniao Browser for authorization, and never operate under an unfamiliar or public network.)
  4. After authorization is complete, the system automatically saves the token; the browser jumps to a success/failure page
  5. call authorized_stores.py, confirm that there is a record for appType=erp(or empty; historical records are regarded as erp)

2. Ad application authorization (AD)

  1. call authorized_stores.py, check whether the target store already has appType=ad
  2. when unauthorized, call authorize_url.py, pass appType=ad, and clearly tell the user that this isad applicationauthorization (unrelated to ERP)
  3. after authorization is complete, check again appType=ad
  4. Prohibitedusing ERP authorization instead of ad authorization

3. Need both ERP and ads

  1. check separately appType=erp and appType=ad
  2. generate authorization addresses only for the missing applications; if both are missing, generatetwo URLs, and label their purposes
  3. prompt the user that they need to open them separately and complete two authorizations; one authorization will not cover the other capability

4. List authorized stores

call authorized_stores.py, display shopName / shopId / merchantId / region / **appType**. The same store may have two entries, ERP and AD.

5. Prepare store selection information for downstream (high frequency)

the user only speaks in natural language ("my Shopee store", "that store 67890"),do not make the user report a lengthy token。

User context Agent action
only 1 store authorized (and the target capability is authorized) directly take that store's shopId(or merchantId), do not ask
≥ 2 authorized + only store name given clarify with the user by shopName Clarify with the user
Also provide shopName or shopId Directly locate
Explicitly provide shopId / merchantId Directly use
The shop exists in the list but is missing the target appType Initiate the corresponding authorization based on the capability,Do notCall business APIs

Silent principle: when location succeeds, only confirm the shop identifier and application type; do not ask the user for a token.

Recommended process：authorized_stores.py By shopId + appType Confirm authorization via → downstream skill directly POST /shopee/developerProxy Pass in shopId(or merchantId) and the server resolves the corresponding application token by path.

store_tokens.py Only used toConfirm authorization/token status (must pass appType），Do notFor proxy calls, first obtain accessToken。

Calling principles

  • Before authorization, it is recommended to confirm shopName、region、appType
  • Do not assume storeTokens the response contains raw accessToken; displaying the status and expiry metadata is sufficient
  • Explain the cause of authorization failures according to error codes; do not retry on your own
  • If the token is expired, follow the corresponding appType to go through the authorization process again
  • Historical empty app_type is regarded as ERP, not AD

FAQ

Authorization is complete but the shop cannot be found

Cause: Token push callback (/shopee/oauth/tokenCallback) was not successfully persisted, or state does not match. Solution: check the service logs; call again authorize_url.py(do not reuse an expired URL) to complete authorization.

Token lookup / business call returns 1004

Cause:shopId / merchantId error, orTarget applicationis not authorized (for example, only ERP, no AD). Solution: first call authorized_stores.py to verify shopId + appType; if missing, reauthorize according to the capability.

The shop is authorized but the Ads API fails

Cause: having an ERP record ≠ having an AD record; Ads cannot use an ERP Token. Solution: initiate appType=ad authorization, then call linkfox-shopee-store-ads。

Not Applicable

  • Shopee Order Query and Processing → linkfox-shopee-store-orders
  • Shopee Shop Information and Settings → linkfox-shopee-store-shop
  • Shopee Shop Product listing → linkfox-shopee-store-product
  • Shopee Cross-border Global Product GlobalProduct → linkfox-shopee-store-global-product
  • Shopee Cross-border Merchant Information Merchant → linkfox-shopee-store-merchant
  • Shopee Logistics Shipping Logistics → linkfox-shopee-store-logistics
  • Shopee Returns and Refunds Returns → linkfox-shopee-store-returns
  • Shopee On-platform Ads Ads → linkfox-shopee-store-ads(business call; authorization still uses this skill's appType=ad）
  • Shopee Payments and Settlement Payment → linkfox-shopee-store-payment
  • Shopee Affiliate Marketing AMS → linkfox-shopee-store-ams
  • Shopee Shop Video Video → linkfox-shopee-store-video
  • Shopee Media Upload MediaSpace → linkfox-shopee-store-media-space
  • Shopee Media Upload Media → linkfox-shopee-store-media（api/v2/media/...，module=130）
  • Shopee First-Mile Logistics FirstMile → linkfox-shopee-store-first-mile
  • Shopee Discount Promotion Discount → linkfox-shopee-store-discount
  • Shopee Bundle Deal Bundle Deal → linkfox-shopee-store-bundle-deal
  • Shopee Add-On Deal Add-On Deal → linkfox-shopee-store-add-on-deal
  • Shopee Shop Voucher Voucher → linkfox-shopee-store-voucher
  • Shopee Shop Flash Sale Shop Flash Sale → linkfox-shopee-store-shop-flash-sale
  • Shopee Follow Prize Follow Prize → linkfox-shopee-store-follow-prize
  • Shopee Top Picks Top Picks → linkfox-shopee-store-top-picks
  • Shopee Shop Category Shop Category → linkfox-shopee-store-shop-category
  • Shopee Account Health Account Health → linkfox-shopee-store-account-health
  • Shopee Public Common Module → linkfox-shopee-store-public（v2.public.* Underlying OAuth / Partner query)
  • Shopee Push push mechanism → linkfox-shopee-store-push
  • Shopee SBS warehousing service → linkfox-shopee-store-sbs
  • Shopee FBS Brazil warehousing → linkfox-shopee-store-fbs
  • Shopee Livestream → linkfox-shopee-store-livestream
  • Shopee product selection (Youying) → linkfox-youying-shopee-product-search
  • Product listing management → dedicated product skill or developerProxy Product API

Computing power consumption rules

Does not consume computing power.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.