TikTok / Shopee 订单归因与接口调用说明

1. 先讲清楚：什么叫订单归因

BeeX 的“订单归因”不是单纯“订单同步到了”。真正完整的归因要同时完成三件事：

核心数据流

sequenceDiagram
  participant U as 用户 App/H5
  participant B as BeeX 服务端
  participant C as affiliate_clicks
  participant P as TikTok/Shopee
  participant O as affiliate_orders

  U->>B: 生成返佣链接 /api/v1/affiliate-links/generate
  B->>C: 写入 click_id、tracking_tag、tracking_code、商品图、商品链接
  B->>P: 调平台转链接口，写入平台可回传的归因字段
  P-->>U: 返回可购买链接
  U->>P: 点击链接并下单
  B->>P: 定时拉订单报表
  P-->>B: 返回订单 raw payload + 平台归因字段
  B->>C: 从回传字段提取 tracking_code 并精确匹配
  alt TikTok 未回传 tracking_code
    B->>C: 按同商品 + 下单前时间窗口匹配最近点击
  end
  B->>O: 写入订单，click_id 不为空则完整归因
    

2. TikTok Shop 订单归因

2.1 App/H5 调 BeeX 生成链接

POST https://api-id-test.beexofficial.com/api/v1/affiliate-links/generate
Content-Type: application/json
Authorization: Bearer {BeeX access token}

{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "userId": "usr_xxx",
  "referralCode": "BXH6G4QAHC",
  "deviceId": "AVPHuSdhJDxyq7WEqDYlihI",
  "channel": "h5",
  "productUrl": "https://vt.tokopedia.com/t/...",
  "platformProductId": "1733045523587827027"
}

2.2 BeeX 调 TikTok Creator 生成分享链接

{
  "material": {
    "ids": ["1733045523587827027"],
    "type": "PRODUCT"
  },
  "channel": "h5",
  "tags": [
    "sx_id_test_usr_mqrvovngf8ofkk2ctnlr_BXH6G4QAHC_063hygm7"
  ]
}

上面是 general_publishers 路径的 body。经典 202501 路径使用 material.id 和 material.type="1"。两种格式由客户端根据配置路径自动选择。

如果 TikTok 返回的分享链接没有内嵌归因字段，BeeX 还会追加这些参数：

event_id={clickId}
publisher_id={userId}
publisher_name={referralCode}
device_type=1
device_id={deviceId}
referrer_src={channel}
beex_env={idtest/idprod/...}

2.3 BeeX 同步 TikTok 订单

POST https://open-api.tiktokglobalshop.com/affiliate_partner/202603/cap_order/search
Headers:
  x-tts-access-token: {CAP access token}
Query:
  app_key={app_key}
  timestamp={unix_seconds}
  sign={signature}
  category_asset_cipher={Creator Management cipher}
Body:
{
  "create_time_ge": 1780000000,
  "create_time_lt": 1780003600,
  "page_size": 50,
  "page_token": "..."
}

2.4 TikTok 匹配顺序

3. Shopee 订单归因

Shopee 和 TikTok 不一样：Shopee 的订单报表主要通过 conversionReport.utmContent 回传 BeeX 放进去的 subIds。 之前 BeeX 把 userId、邀请码、click 尾巴都塞进去，字段太长且段数多，实际回传可能截断。现在改为短码方案。

3.1 旧方案的问题

3.2 新方案：短 tracking_code

当前生成 Shopee 短链时，BeeX 只传一个短 tracking_code。平台和环境信息已经编码在短码内部，不再额外占用一个 subId：

tracking_code 生成规则：
1. 固定前缀 c
2. 平台字符：t=TikTok、s=Shopee、l=Lazada
3. 环境字符：t=test、p=prod
4. clickId 去掉非字母数字后取最后 10 位

格式：c<platform><env><last10>

3.3 BeeX 调 Shopee 生成短链

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

mutation {
  generateShortLink(input: {
    originUrl: "https://shopee.co.id/product/1582467379/49112548266",
    subIds: ["cstxxxxxxxxxx"]
  }) {
    shortLink
    longLink
  }
}

BeeX 会把返回值保存为：

3.4 BeeX 同步 Shopee 订单

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

{
  conversionReport(
    purchaseTimeStart: 1780000000,
    purchaseTimeEnd: 1780003600,
    orderStatus: PENDING,
    limit: 50,
    scrollId: "..."
  ) {
    nodes {
      clickTime
      purchaseTime
      conversionId
      conversionStatus
      totalCommission
      netCommission
      utmContent
      device
      orders {
        orderId
        orderStatus
        items {
          itemId
          itemName
          shopId
          shopName
          actualAmount
          itemTotalCommission
          completeTime
          fraudStatus
        }
      }
    }
    pageInfo {
      scrollId
      hasNextPage
    }
  }
}

3.5 Shopee 匹配顺序

4. 排查手册：订单同步了但 click_id 为空怎么办

4.1 先区分问题类型

4.2 SQL 检查模板

-- 1. 看订单是否有 click_id，以及原始平台返回
select id,
       platform,
       platform_order_id,
       user_id,
       click_id,
       ordered_at,
       status,
       raw_payload
from affiliate_orders
where platform_order_id = '260701GQ5Y2TH5';

-- 2. 如果知道 click_id，查点击记录
select id,
       country_code,
       platform,
       user_id,
       referral_code,
       tracking_tag,
       tracking_code,
       product_url,
       affiliate_url,
       product_name,
       image_url,
       clicked_at
from affiliate_clicks
where id = 'clk_mr1hvv0jynii063hygm7';

-- 3. Shopee 新归因：用短码反查
select id,
       user_id,
       tracking_code,
       product_url,
       affiliate_url,
       image_url,
       clicked_at
from affiliate_clicks
where country_code = 'ID'
  and platform = 'SHOPEE'
  and tracking_code = 'cstxxxxxxxxxx';

4.3 平台 raw payload 重点字段

4.4 开发约束

• Shopee 的 subIds 只传统一短 tracking_code，不要恢复成长 userId 方案，也不要再单独传环境段。
• TikTok 的订单 raw payload 必须完整保存，平台回传字段不稳定时，raw 是唯一排查依据。
• affiliate_orders.click_id 为空时，不要在对外接口暴露平台佣金细节，只能展示用户应得返佣。
• 商品图缺失时，先查 click_id，不要先怀疑前端图片组件。
• 所有新平台都要先设计“生成链接字段”和“订单回传字段”的闭环，再上线订单同步。

4.5 给平台技术支持的验证问题