BeeX App 首页商品列表到购买链路接口说明

本文说明 App/H5 首页 ALL 列表的数据来源、点击商品进入详情页、点击跳转 TikTok/Shopee 下单时的完整接口链路。

1. 先回答一个关键问题

首页列表查到的商品信息，和单独拿一个商品链接去解析得到的商品信息，不保证完全一样。

原因如下：

首页列表是“商品摘要列表”，目标是快速展示和分页，来源可能是 Shopee 商品池、TikTok Creator open collaboration、TikTok Partner Campaign 缓存。
商品详情页会先使用列表带过去的摘要数据秒开，然后如果路由里有 url，会再调用 /api/v1/products/resolve 按商品链接做单商品解析，刷新商品详情。
对 TikTok 高返佣商品，列表来源可能是 Partner Campaign 缓存；单商品解析会优先查 Campaign 缓存，再查 Creator 商品详情接口，再查 Creator 搜索接口，最后才兜底。
对 Shopee 商品，列表和详情都基于 Shopee Affiliate productOfferV2，但列表可能是搜索结果，详情是按 itemId/shopId 精确解析，返回的新鲜度和字段完整度可能不同。
对 Shopee 高返佣/AMS 商品，当前已验证单商品 itemId 查询也可以拿到高返佣；首页高返佣推荐池的定时同步与缓存仍待实现。
用户看到的返现金额必须以 BeeX 后端返回的 cashbackMinor 为准，不能用前端自己按平台佣金比例推算。

字段口径：

字段	含义	前端用途
`platformProductId`	平台商品 ID	商品详情、转链、订单归因
`imageUrl`	商品主图	列表卡片、详情页主图
`priceMinor`	商品价格，minor 单位	展示价格，前端显示时除以 100 后向下取整
`cashbackMinor`	用户可见返现，minor 单位	展示“预计返现”，前端显示时除以 100 后向下取整
`productUrl`	平台商品 PDP 链接	详情解析、转链、跳转平台
`source`	BeeX 商品来源	排查商品来自普通联盟还是高返佣 Campaign

PDP 是 Product Detail Page，即平台商品详情页链接。例如 TikTok Indonesia 当前用：

https://shop-id.tokopedia.com/view/product/{productId}?region=ID&local=en

2. 整体链路图

sequenceDiagram
    participant H5 as BeeX H5 首页
    participant API as BeeX API
    participant Shopee as Shopee Affiliate API
    participant TKCreator as TikTok Creator API
    participant TKCampaign as TikTok Partner Campaign Cache/API
    participant Detail as BeeX 商品详情页
    participant Platform as TikTok/Shopee App or Web

    H5->>API: POST /api/v1/products/high-commission (ALL)
    API->>Shopee: productOfferV2
    API->>TKCampaign: 读取本地 Campaign 商品缓存
    API->>TKCreator: Search Open Collaboration Products
    API-->>H5: products + pageInfo
    H5->>Detail: 保存商品摘要到 sessionStorage, 跳转 /product-detail
    Detail->>API: POST /api/v1/products/resolve
    API-->>Detail: 单商品详情
    Detail->>API: POST /api/v1/products/recommendations (SHOP)
    Detail->>API: POST /api/v1/products/recommendations (CATEGORY)
    Detail->>API: POST /api/v1/coupons/preview (已登录时)
    Detail->>API: POST /api/v1/affiliate-links/generate
    API->>Shopee: Shopee short link generate (Shopee 商品)
    API->>TKCreator: Creator sharing link generate (所有 TikTok 商品)
    API-->>Detail: affiliateUrl
    Detail->>Platform: openExternalUrl(affiliateUrl)

3. 首页 ALL 列表

3.1 H5 调 BeeX 后端

首页 ALL Tab 使用：

POST https://api-id-test.beexofficial.com/api/v1/products/high-commission
Content-Type: application/json

请求体：

{
  "countryCode": "ID",
  "limit": 10
}

分页加载下一页时：

{
  "countryCode": "ID",
  "limit": 10,
  "cursor": "page:2"
}

搜索时：

{
  "countryCode": "ID",
  "limit": 20,
  "keyword": "nike"
}

3.2 H5 侧缓存策略

首页商品列表在 H5 本地缓存 72 小时。进入首页时会先读缓存，页面先渲染；然后后台刷新接口，拿到新数据后覆盖缓存并刷新界面。

当前首页只保留这些 Tab：

Tab	请求参数
ALL	不传 `platform`，不传 `source`
高返佣	`source=PARTNER_CAMPAIGN`
TikTok	`platform=TIKTOK`
Shopee	`platform=SHOPEE`

3.3 BeeX 后端内部数据来源

当 platform 为空，也就是 ALL，后端会合并以下来源：

Shopee Affiliate productOfferV2
TikTok Partner Campaign 本地缓存
TikTok Creator Search Open Collaboration Products

后端会去重、按用户可见返现 cashbackMinor 排序，再分页返回。

3.3.1 Shopee AMS 高返佣补充

Shopee 的高返佣商品当前仍通过 Affiliate productOfferV2 查询。BeeX 客户端已经支持 matchId、listType 和 isAMSOffer 参数，也支持按 itemId/shopId 实时查询单商品。

能力	当前状态
单商品高佣查询	已实现；用户粘贴链接后按 `itemId/shopId` 实时查询。
AMS 商品池调试查询	已验证特定 `matchId + amsOffer=true` 能返回高佣 Offer。
AMS 定时同步、缓存表、首页运营池	待实现，当前不能写成已上线能力。

详细接口样例、字段口径和待确认问题见 Shopee AMS 高返佣商品池说明。

3.4 商品过滤规则

首页列表、推荐列表、蜜源圈可选商品池都属于 C 端主动推荐内容。进入 App/H5 列表前，后端必须先过滤掉无法形成“详情 -> 转链 -> 下单”闭环的商品，避免用户看到高返佣但点进平台后不能购买。

过滤发生在 BeeX 后端，不由前端兜底。前端只负责在异常情况下记录日志并隐藏购买按钮。

过滤维度	过滤条件	说明
购买入口	`productUrl`、`offerLink`、`affiliateUrl` 都为空，且 TikTok 商品无法用 `productId` 生成 PDP	没有稳定购买入口的商品不进入 C 端列表。
商品价格	`priceMinor <= 0` 或平台价格字段为空	首页和推荐列表不展示价格为 0 的商品。
用户返现	`cashbackMinor <= 0`	C 端推荐列表只展示用户可见返现大于 0 的商品。
活动/Offer 有效期	当前时间不在平台 `periodStartTime/periodEndTime` 内	Shopee `periodEndTime` 可能是秒级时间戳，后端需要统一转为毫秒后判断。
TikTok Campaign 状态	Campaign 非可用状态，或商品 `review_status != APPROVED`	高返佣 Campaign 列表只保留已经审核通过、可推广的商品。
库存/售罄	平台返回 `stock=0`、`availableStock=0`、`soldOut=true`、`outOfStock=true` 等字段	只要平台字段能识别为无库存，就过滤。
店铺休假/不可购买	平台返回 `isSellerOnVacation=true`、`shopVacation=true`、`canBuy=false`、`purchasable=false`、`available=false` 等字段	类似“seller currently on vacation”的商品，如果平台接口返回对应状态，后端直接过滤。
下架/关闭/异常状态	平台返回 `status=INACTIVE/DISABLED/DELETED/BANNED/SUSPENDED/CLOSED/EXPIRED/REJECTED` 等状态	这类商品不进入首页、推荐和高返佣列表。

边界说明：

如果平台接口没有返回“店铺休假/不可购买/售罄”字段，BeeX 无法 100% 提前识别，只能在用户打开平台后由平台提示。
对这类平台未返回状态的问题，后续需要补“商品/店铺黑名单”和“跳转失败反馈”能力：用户或运营发现不可购买商品后，按 platform + itemId/shopId 禁用，下一次列表不再返回。
过滤后的商品仍然可能因为平台实时状态变化而失效，所以前端文案要使用“预计返现”“预计价格”，不要承诺一定可买。

Shopee 内部请求

BeeX 后端会调用 Shopee Affiliate GraphQL：

POST https://open-api.affiliate.shopee.co.id/graphql
Content-Type: application/json
Authorization: SHA256 Credential={AppID}, Timestamp={timestamp}, Signature={signature}

GraphQL 能力：

{
  productOfferV2 {
    nodes {
      itemId
      shopId
      productName
      imageUrl
      productLink
      offerLink
      price
      periodStartTime
      periodEndTime
      commissionRate
      commission
      shopName
      productCatIds
      sales
      ratingStar
    }
    pageInfo {
      page
      limit
      hasNextPage
      scrollId
    }
  }
}

TikTok Creator 内部请求

BeeX 后端会调用 TikTok Creator 商品搜索：

POST https://open-api.tiktokglobalshop.com/affiliate_creator/202405/open_collaborations/products/search?page_size=20&app_key={app_key}&timestamp={timestamp}&sign={sign}
x-tts-access-token: {creator_access_token}
Content-Type: application/json

无关键词时 body 可以为空对象：

{}

有关键词时：

{
  "keyword": "nike"
}

TikTok Partner Campaign 来源

首页 ALL 会合并本地缓存里的 Campaign 商品。这个缓存由定时任务从 TikTok Partner Campaign API 同步：

GET /affiliate_partner/202405/campaigns
GET /affiliate_partner/202405/campaigns/{campaign_id}/products

注意：TikTok Campaign 商品列表原始返回通常有 main_image_url，但不一定有平台 PDP 链接。因此 BeeX 需要用 productId 兜底生成：

https://shop-id.tokopedia.com/view/product/{productId}?region=ID&local=en

否则高返佣商品可能能展示图片，但点击详情或跳转购买时没有稳定的商品原链。后端返回 C 端列表前必须做购买入口校验：能用 productId 生成 PDP 的 TikTok 商品保留；无法生成平台 PDP 的商品直接过滤，不进入 App 列表。

3.5 BeeX 返回给 H5 的样例

请求：

curl -X POST 'https://api-id-test.beexofficial.com/api/v1/products/high-commission' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","limit":2}'

响应样例：

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "products": [
      {
        "id": "tiktok-1729603134232627949",
        "platformProductId": "1729603134232627949",
        "name": "KURSI_GAMING_CYGNUSBIRU_HITAM",
        "brand": "Informa Duta Mall Banjarmasin",
        "platform": "TIKTOK",
        "imageUrl": "https://p16-oec-va.ibyteimg.com/...",
        "shopName": "Informa Duta Mall Banjarmasin",
        "categoryId": "876040",
        "categoryName": "Chairs",
        "cashbackMinor": 153024000,
        "priceMinor": 318800000,
        "currency": "IDR",
        "productUrl": "https://shop-id.tokopedia.com/view/product/1729603134232627949?region=ID&local=en",
        "source": "tiktok.open_collaboration_product_search"
      },
      {
        "id": "shopee-26955475977",
        "platformProductId": "26955475977",
        "name": "Apple iPhone 13 128 GB",
        "brand": "ALPHAINDONUSA",
        "platform": "SHOPEE",
        "imageUrl": "https://cf.shopee.co.id/file/...",
        "shopId": "124397491",
        "shopName": "ALPHAINDONUSA",
        "categoryId": "100073",
        "cashbackMinor": 133200000,
        "priceMinor": 1110000000,
        "currency": "IDR",
        "productUrl": "https://shopee.co.id/product/124397491/26955475977",
        "source": "shopee.productOfferV2"
      }
    ],
    "pageInfo": {
      "hasNext": true,
      "nextCursor": "page:2",
      "pageSize": 2
    },
    "warnings": []
  }
}

4. 点击商品打开详情页

4.1 H5 页面跳转

用户点击商品卡片后，H5 不会立刻丢掉列表数据，而是：

把当前商品摘要和已有 affiliateLink 存入 sessionStorage
跳转到：

/product-detail?key={sessionKey}&url={productUrl}

这样详情页可以先显示列表已有的 imageUrl/name/priceMinor/cashbackMinor，再异步刷新单商品详情。

4.2 详情页解析商品

如果路由里有 url，详情页会调用：

POST https://api-id-test.beexofficial.com/api/v1/products/resolve
Content-Type: application/json

请求体：

{
  "countryCode": "ID",
  "productUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?region=ID&local=en",
  "userId": "usr_xxx"
}

userId 未登录时不传。

响应样例：

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "id": "tiktok-1730961924391601456",
    "platformProductId": "1730961924391601456",
    "name": "L'Oreal Paris Fall Resist X3 Shampoo & Conditioner",
    "brand": "L'Oreal Paris Haircare",
    "platform": "TIKTOK",
    "imageUrl": "https://p16-oec-sg.ibyteimg.com/...",
    "shopName": "L'Oreal Paris Haircare",
    "categoryId": "601469",
    "categoryName": "Sampo & Kondisioner",
    "cashbackMinor": 394100,
    "priceMinor": 7990000,
    "currency": "IDR",
    "category": "Sampo & Kondisioner",
    "productUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?region=ID&local=en",
    "source": "tiktok.open_collaboration_product_ids"
  }
}

4.3 BeeX 后端单商品解析顺序

TikTok 商品

后端解析顺序：

解析短链，得到真实 TikTok/Tokopedia PDP 链接和 productId
查 TikTok Partner Campaign 本地缓存，命中说明是高返佣商品
调 TikTok Creator open_collaborations/products?product_ids=...
调 TikTok Creator 搜索接口兜底
全部失败时生成 fallback 商品，返现为 0

Shopee 商品

后端解析顺序：

解析 Shopee 短链，得到真实商品链接
从链接里解析 shopId/itemId
调 Shopee productOfferV2 查询商品和佣金
全部失败时生成 fallback 商品，返现为 0

5. 商品详情页附加请求

详情页除了商品主信息，还会发下面几个请求。

5.1 店铺相关推荐

POST https://api-id-test.beexofficial.com/api/v1/products/recommendations
Content-Type: application/json

请求体：

{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "scene": "SHOP",
  "shopName": "L'Oreal Paris Haircare",
  "excludeProductId": "tiktok-1730961924391601456",
  "excludePlatformProductId": "1730961924391601456",
  "pageSize": 9
}

5.2 品类相关推荐

POST https://api-id-test.beexofficial.com/api/v1/products/recommendations
Content-Type: application/json

请求体：

{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "scene": "CATEGORY",
  "categoryId": "601469",
  "categoryName": "Sampo & Kondisioner",
  "excludeProductId": "tiktok-1730961924391601456",
  "excludePlatformProductId": "1730961924391601456",
  "pageSize": 20
}

5.3 优惠券预览

只有用户已登录时才会调用：

POST https://api-id-test.beexofficial.com/api/v1/coupons/preview
Content-Type: application/json

请求体：

{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "bizType": "AFFILIATE_ORDER",
  "amountMinor": 394100,
  "couponId": "ucp_xxx"
}

amountMinor 这里传的是当前商品的用户基础返现 cashbackMinor，用于判断返佣券能额外加多少钱。

6. 点击跳转到 TikTok/Shopee 下单

6.1 H5 调 BeeX 生成购买链接

如果当前详情页还没有 affiliateLink，点击“去平台下单”会调用：

POST https://api-id-test.beexofficial.com/api/v1/affiliate-links/generate
Content-Type: application/json

请求体：

{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "productUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?region=ID&local=en",
  "platformProductId": "1730961924391601456",
  "linkMode": "DIRECT",
  "productName": "L'Oreal Paris Fall Resist X3 Shampoo & Conditioner",
  "imageUrl": "https://p16-oec-sg.ibyteimg.com/...",
  "priceMinor": 7990000,
  "cashbackMinor": 394100,
  "currency": "IDR",
  "couponId": "ucp_xxx",
  "channel": "h5",
  "deviceId": "device_xxx"
}

linkMode=DIRECT 表示直接购买链接。分享裂变链接使用 linkMode=SHARE。

6.2 BeeX 后端转链逻辑

TikTok

从请求的 platformProductId 或商品 URL 提取 productId。
当前所有 TikTok 商品统一调用 Creator 分享链接接口，不再调用 Partner Campaign promotion link：

POST ${SEAHUB_TIKTOK_CREATOR_SHARING_LINK_PATH}

代码默认路径是 /affiliate_creator/202501/affiliate_sharing_links/generate_batch；部署环境也可以配置为 /affiliate_creator/202505/affiliate_sharing_links/general_publishers/generate_batch，客户端会根据路径自动切换 body 格式。

BeeX 生成统一短 trackingCode，同时传入 TikTok tags 并追加 event_id/sx_ac/publisher_id/device_id 等归因参数。
成功后写入 affiliate_clicks；Creator 授权缺失或接口失败时直接返回错误，不会用原始商品链接伪装成返佣链接。

边界：Partner Campaign 仍用于高返佣商品发现、佣金展示和推荐池缓存，但当前不参与 C 端购买转链。

Shopee

解析原始 Shopee 商品链接
调 Shopee Affiliate 短链/转链能力
写入 affiliate_clicks

6.3 BeeX 返回 H5

响应字段：

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "clickId": "clk_xxx",
    "platform": "TIKTOK",
    "originalUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?region=ID&local=en",
    "affiliateUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?...&event_id=clk_xxx&publisher_id=usr_xxx",
    "purchaseUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?...",
    "shareUrl": null,
    "shareCode": null,
    "linkMode": "DIRECT",
    "longAffiliateUrl": "...",
    "appOpenUrl": "...",
    "deepLink": "...",
    "trackingTag": "clk_xxx",
    "note": "..."
  }
}

H5 使用 affiliateUrl 调 openExternalUrl 打开平台。如果系统能唤起 App，会进入 TikTok/Shopee App；否则会先进入浏览器，再由平台引导打开 App。

7. 当前需要特别注意的问题

PARTNER_CAMPAIGN 商品原始接口不保证返回 PDP 链接，BeeX 后端必须用 platformProductId 生成 TikTok/Tokopedia PDP。
如果商品最终仍没有 productUrl，说明无法完成“详情 -> 转链 -> 下单”闭环，后端应直接过滤，不返回给 App/H5。
对外给 App/H5 的商品字段不能暴露平台给 BeeX 的原始佣金，只能暴露用户可见的 cashbackMinor。
用户看到的钱统一从 minor 转展示值：显示金额 = floor(minor / 100)。
平台没有返回不可购买状态时，BeeX 只能靠黑名单和用户反馈补充拦截；不能把平台 App 内实时提示当成 BeeX 后端必然可提前识别的信息。