BeeX App 原始商品链接转链到购买链路接口说明

本文说明用户在 App/H5 粘贴 TikTok、Shopee 或 Lazada 原始商品链接后，BeeX 如何解析商品、生成返佣链接、打开商品详情页、再跳转平台购买。

1. 这条链路和首页列表链路的区别

首页列表链路是“先拿商品列表，再点商品”；原始链接转链链路是“用户先给一个商品链接，再解析这个单品”。

两条链路最终都会进入同一个商品详情页，并且点击购买时都会走 /api/v1/affiliate-links/generate。区别在于：

环节	首页列表链路	原始链接转链链路
商品来源	`/products/high-commission` 返回列表摘要	用户提供 TikTok/Shopee/Lazada 原始链接
详情打开前是否已有商品信息	有，列表卡片已有摘要	不一定，需要先 resolve
是否提前生成购买返佣链接	通常没有，点击购买才生成	用户提交链接时会先生成一次 affiliateLink
商品详情页点击购买	如果已有 affiliateLink，直接打开；否则再生成	通常直接打开已生成的 affiliateLink

2. 整体链路图

sequenceDiagram
    participant User as 用户
    participant H5 as BeeX H5
    participant API as BeeX API
    participant Shopee as Shopee Affiliate API
    participant TKCampaign as TikTok Campaign 本地缓存
    participant TKCreator as TikTok Creator API
    participant Lazada as Lazada Affiliate API
    participant Detail as BeeX 商品详情页
    participant Platform as TikTok/Shopee/Lazada App or Web

    User->>H5: 粘贴 TikTok/Shopee/Lazada 商品链接
    H5->>API: POST /api/v1/products/resolve
    API->>Shopee: productOfferV2 (Shopee)
    API->>TKCampaign: 查本地 Campaign 缓存 (TikTok)
    API->>TKCreator: product_ids/search (TikTok)
    API->>Lazada: productInfoByUrl/productId (Lazada)
    API-->>H5: 商品详情
    H5->>API: POST /api/v1/affiliate-links/generate
    API->>TKCreator: Creator sharing link generate (TikTok C 端固定链路)
    API->>Shopee: Shopee short link generate (Shopee)
    API->>Lazada: affiliate link generate (Lazada)
    API-->>H5: affiliateLink
    H5->>Detail: 保存 product + affiliateLink, 打开商品详情页
    Detail->>API: POST /api/v1/products/resolve (有 url 时刷新详情)
    Detail->>API: POST /api/v1/products/recommendations
    Detail->>API: POST /api/v1/coupons/preview (已登录时)
    Detail->>Platform: openExternalUrl(affiliateUrl)

3. 用户粘贴链接入口

3.1 链接识别

H5 会从用户输入或剪切板文本中提取第一个购物链接。

支持形态示例：

https://vt.tokopedia.com/t/ZS9jXgbFAqRXP-Wcl8G/

Temukan produk ini di Shopee! https://id.shp.ee/MqaXefip

https://s.shopee.co.id/3VhpbrtKN7

https://s.lazada.co.id/s.Zo6VrC?c=v&t=...

识别到链接后，H5 会判断是否是 TikTok/Tokopedia、Shopee 或 Lazada 支持的商品链接。

3.2 剪切板自动识别

App 切回前台时，如果剪切板里有商品链接，H5 会先调用商品解析接口，用于弹出“发现了一个可返现商品”的弹层。

这一步只解析商品，不一定立即生成返佣链接。

4. 第一步：解析原始商品链接

4.1 H5 调 BeeX

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

请求体：

{
  "countryCode": "ID",
  "productUrl": "https://vt.tokopedia.com/t/ZS9jXgbFAqRXP-Wcl8G/",
  "userId": "usr_xxx"
}

userId 未登录时不传。

4.2 BeeX 后端解析逻辑

TikTok/Tokopedia 链接

如果是短链，先跟随跳转解析真实 URL
从真实 URL 中提取 productId
查 BeeX 本地 TikTok Partner Campaign 商品缓存
查 TikTok Creator 商品 ID 接口
查 TikTok Creator 商品搜索接口
如果都失败，返回 fallback 商品，cashbackMinor=0

TikTok Creator 商品 ID 接口：

POST /affiliate_creator/202509/open_collaborations/products?product_ids={productId}

TikTok Creator 搜索接口：

POST /affiliate_creator/202405/open_collaborations/products/search?page_size=20

Shopee 链接

如果是短链，先跟随跳转解析真实 URL
从真实 URL 中提取 shopId/itemId
调 Shopee Affiliate productOfferV2
如果查不到，返回 fallback 商品，cashbackMinor=0

Lazada 链接

如果是 s.lazada.co.id 短链，先跟随跳转并提取可用的商品标识
优先调用 Lazada Affiliate 商品信息能力补全标题、主图、价格和返佣信息
必要时按 productId 反查商品详情
平台信息不足时只返回可解释的 fallback 商品，不承诺返现

4.3 单品解析的过滤和兜底

用户主动粘贴链接时，处理口径和首页列表不完全一样：

如果平台返回明确不可购买状态，例如售罄、无库存、店铺休假、下架、活动过期，服务端应返回商品快照但标记为不可转链或返现为 0，前端不展示“去平台下单”按钮。
如果平台只是没有返回佣金，允许返回 fallback 商品，但 cashbackMinor=0，并提示“当前暂不支持返现”。
如果商品有价格、返现和购买入口，才允许继续调用 /api/v1/affiliate-links/generate。
如果平台接口没有返回店铺休假、不可购买等实时状态，BeeX 无法提前识别，只能在用户打开平台后由平台提示；这类问题要通过后续黑名单或跳转失败反馈补充拦截。

与首页列表不同：列表要“宁可少展示，也不要推荐坏商品”；用户主动粘贴链接时可以给出解释和兜底结果，但不能承诺返现和可购买。

4.4 BeeX 返回样例

请求：

curl -X POST 'https://api-id-test.beexofficial.com/api/v1/products/resolve' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","productUrl":"https://vt.tokopedia.com/t/ZS9jXgbFAqRXP-Wcl8G/"}'

响应样例：

{
  "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"
  }
}

5. 第二步：生成 BeeX 返佣链接

用户正式提交转链时必须登录，因为转链要绑定 BeeX 用户、设备和归因关系。

5.1 H5 调 BeeX

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

请求体：

{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "productUrl": "https://vt.tokopedia.com/t/ZS9jXgbFAqRXP-Wcl8G/",
  "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"
}

5.2 TikTok 转链

面向 BeeX App 用户的 C 端购买链接固定使用 Creator Sharing Link：

POST /affiliate_creator/202505/affiliate_sharing_links/general_publishers/generate_batch

TikTok Partner Campaign 接口当前只用于 Campaign 商品发现、高返佣分类和本地缓存，不参与 C 端购买链接生成。即使商品命中 Campaign，也不能调用 Campaign promotion link 代替 Creator 链接。

Creator 转链不可用时，服务端才按可用信息返回原始 PDP 兜底；兜底链接不能被视为已完成联盟归因。

5.3 Shopee 转链

Shopee 转链使用 Shopee Affiliate 的短链/转链能力。BeeX 会把用户 ID、点击 ID、设备 ID 放入 subId 或追踪参数，用于后续订单归因。

5.4 Lazada 转链

Lazada 使用 Affiliate Open API 生成平台返佣链接。服务端优先使用解析后的商品 URL 或 productId 生成链接，并保存 BeeX 点击记录；平台无法返回可用 Affiliate Link 时，不得把普通商品 URL 宣称为返佣链接。

5.5 BeeX 返回给 H5

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "data": {
    "clickId": "clk_xxx",
    "platform": "TIKTOK",
    "originalUrl": "https://vt.tokopedia.com/t/ZS9jXgbFAqRXP-Wcl8G/",
    "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",
    "trackingTag": "clk_xxx",
    "note": "..."
  }
}

BeeX 同时会写入 affiliate_clicks，用于后续订单追踪和归因。

6. 第三步：打开商品详情页

H5 生成返佣链接后，会把以下内容存到 sessionStorage：

{
  "product": {
    "platformProductId": "1730961924391601456",
    "name": "L'Oreal Paris Fall Resist X3 Shampoo & Conditioner",
    "imageUrl": "https://p16-oec-sg.ibyteimg.com/...",
    "priceMinor": 7990000,
    "cashbackMinor": 394100,
    "productUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?region=ID&local=en"
  },
  "affiliateLink": {
    "clickId": "clk_xxx",
    "affiliateUrl": "https://shop-id.tokopedia.com/view/product/1730961924391601456?...",
    "linkMode": "DIRECT"
  }
}

然后跳转：

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

详情页会：

先读取 sessionStorage，立刻显示商品信息
如果 URL 存在，再调用 /api/v1/products/resolve 刷新商品
已登录时调用 /api/v1/coupons/preview 计算可用券
调 /api/v1/products/recommendations 加载店铺推荐和品类推荐

7. 第四步：点击跳转平台购买

如果详情页已经有 affiliateLink.affiliateUrl，点击“去平台下单”时不会再生成一次链接，直接打开：

affiliateLink.affiliateUrl

如果用户刷新页面、session 丢失或没有 affiliateLink，详情页会重新调用：

POST /api/v1/affiliate-links/generate

再打开返回的 affiliateUrl。

8. 异常和兜底

场景	前端表现	后端策略
链接不是 TikTok/Shopee/Lazada	提示不支持	不调转链
短链解析失败	可能生成 fallback 商品	返现为 0
商品查不到佣金	展示商品但返现为 0	fallback 商品
商品明确不可购买	不展示购买按钮，提示商品暂不可返现或不可购买	返回不可转链结果或过滤购买入口
平台未返回不可购买字段	用户可能在平台 App 内才看到失败提示	记录跳转失败，后续进入黑名单/反馈处理
TikTok Creator 转链失败	可能只能打开原始 PDP	返回明确的兜底结果，不宣称已完成返佣归因
Lazada Affiliate 转链失败	提示当前链接暂不支持返现	可保留商品快照，但不返回伪返佣链接
用户未登录	引导登录	不允许生成归属用户的返佣链接

9. 对前端的实现要求

商品详情页展示金额只使用 cashbackMinor 和 priceMinor，不要显示平台原始佣金。
正常情况下后端会保证列表商品有 productUrl。如果前端仍拿到空值，说明该商品不应出现在列表；详情页可用 platformProductId 临时兜底生成 TikTok PDP，但要记录日志方便后端排查：

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

如果商品没有 productUrl 且无法通过 platformProductId 生成 PDP，不展示购买按钮。
点击购买优先使用已有 affiliateLink.affiliateUrl，不要重复生成链接。
如果已有 affiliateLink 但打开失败，可以重新调用 /api/v1/affiliate-links/generate 生成新链接。
用户看到的钱统一从 minor 转展示值：显示金额 = floor(minor / 100)。