# Shopee AMS 高返佣商品池说明

本文记录 BeeX 当前对 Shopee 高返佣商品池的判断和已验证能力。后续如果 Shopee 侧补充更明确的 AMS / Match / Campaign 文档，再在本文基础上修正。

> **状态（2026-07-13）**
>
> - 已实现：`productOfferV2` 请求模型和客户端支持 `matchId`、`listType`、`isAMSOffer`，支持按 `itemId/shopId` 实时查询单商品。
> - 已验证：特定 `matchId` 和 `amsOffer=true` 能返回高佣 Offer，单商品查询也可能直接返回 BeeX 账号可见的高佣佣金。
> - 未实现：独立的 Shopee AMS 定时同步 Worker、缓存表、首页高返佣池运营闭环。
>
> 因此，本文第 5 节是目标方案，不代表当前已经上线。

## 1. 结论

Shopee 侧没有像 TikTok Partner Campaign 一样单独拆出三段接口：

```text
campaign list -> campaign products -> campaign product link generate
```

目前 BeeX 可用的方式是继续走 Shopee Affiliate GraphQL 的 `productOfferV2`，通过以下参数筛选高返佣/AMS 商品：

| 参数 | 当前理解 | 备注 |
| --- | --- | --- |
| `matchId` | Shopee 后台活动、匹配、商品池 ID | 当前已验证 `1130280524` 可以返回商品。 |
| `isAMSOffer` / `amsOffer` | 是否只查 AMS Offer | 当前传 `true` 能返回明显高佣商品。 |
| `listType` | Shopee 商品池列表类型 | 当前 `listType=1` 返回空，`listType=2` 有数据；具体枚举含义需要 Shopee 运营或官方文档确认。 |
| `page` / `limit` | 分页 | `pageInfo.hasNextPage=true` 时继续翻页。 |
| `itemId` / `shopId` | 单商品精确查询 | 高返佣商品即使不带 `matchId`，按 `itemId` 单查也可能返回高佣金。 |

因此，BeeX 的 Shopee 高返佣能力可以先按两层理解：

1. **首页/推荐高返佣商品池**：定时用 `matchId + amsOffer=true` 分页拉取并缓存。
2. **用户粘贴单个 Shopee 商品链接**：按 `itemId/shopId` 实时调用 `productOfferV2` 查询；如果商品本身是 BeeX 账号可见的高返佣商品，接口会直接返回高返佣佣金。

## 2. 已验证接口

BeeX 测试环境已经提供 Shopee Product Offer 调试接口：

```http
POST https://api-id-test.beexofficial.com/api/v1/shopee/product-offers
Content-Type: application/json
```

代码入口：

- `beex-service/seahub-core/src/main/java/com/seahub/x/core/affiliate/ShopeeAffiliateClient.java`
- `beex-service/seahub-core/src/main/java/com/seahub/x/core/affiliate/ShopeeProductOfferRequest.java`
- `beex-service/seahub-core/src/main/java/com/seahub/x/core/affiliate/AffiliateController.java`

该接口请求体透传 BeeX 后端支持的 Shopee `productOfferV2` 查询参数，响应 `data` 为 Shopee 原始 JSON。

## 3. 商品池查询样例

### 3.1 用 matchId 查商品池

请求：

```json
{
  "matchId": 1130280524,
  "limit": 5,
  "page": 1
}
```

验证结果：

```json
{
  "count": 5,
  "pageInfo": {
    "page": 1,
    "limit": 5,
    "hasNextPage": true,
    "scrollId": null
  },
  "sample": {
    "itemId": 26054220244,
    "shopId": 236404283,
    "productName": "kemeja katun polly wanita / Kemeja Polos Cewek / Kemeja Polos Kantor / kemeja KA",
    "commissionRate": "0.1",
    "commission": "2990",
    "sales": 1886,
    "productLink": "https://shopee.co.id/product/236404283/26054220244",
    "offerLink": "https://s.shopee.co.id/18SGlTL9G"
  }
}
```

### 3.2 用 amsOffer 查高返佣商品

请求：

```json
{
  "amsOffer": true,
  "limit": 5,
  "page": 1
}
```

验证结果：

```json
{
  "count": 5,
  "pageInfo": {
    "page": 1,
    "limit": 5,
    "hasNextPage": true,
    "scrollId": null
  },
  "sample": {
    "itemId": 29607813188,
    "shopId": 644589107,
    "productName": "XBOX PC GAME PASS SHARING ORIGINAL",
    "commissionRate": "0.8",
    "commission": "4000",
    "sales": 277,
    "productLink": "https://shopee.co.id/product/644589107/29607813188",
    "offerLink": "https://s.shopee.co.id/2g9GAdpn8u"
  }
}
```

`commissionRate=0.8` 表示 80% 佣金率，明显属于高返佣商品。

### 3.3 matchId + amsOffer

请求：

```json
{
  "matchId": 1130280524,
  "amsOffer": true,
  "limit": 5,
  "page": 1
}
```

验证结果和单独 `amsOffer=true` 一致，能返回高佣商品。后续需要确认 Shopee 是否在当前账号下把 AMS 商品池全局暴露，还是 `matchId` 没有参与过滤。

## 4. 单商品查询是否能拿到高返佣

已验证：可以。

用上面高佣商品 `itemId=29607813188` 只做单品查询：

```json
{
  "itemId": 29607813188,
  "limit": 1,
  "page": 1
}
```

返回：

```json
{
  "itemId": 29607813188,
  "productName": "XBOX PC GAME PASS SHARING ORIGINAL",
  "commissionRate": "0.8",
  "commission": "4000",
  "sellerCommissionRate": "0.8",
  "shopeeCommissionRate": "0",
  "productLink": "https://shopee.co.id/product/644589107/29607813188",
  "offerLink": "https://s.shopee.co.id/2g9GAdpn8u"
}
```

这说明：如果用户粘贴的是 BeeX 账号可见的 Shopee 高返佣商品，当前单商品查询能力也可以拿到高返佣，不依赖提前缓存。

但缓存仍有必要：

1. 首页“高返佣”Tab 需要主动推荐商品池。
2. 不缓存就只能用户贴链接后被动查询，无法做运营推荐。
3. 缓存可以提前过滤无图、低销量、低佣金、无购买入口商品。
4. 缓存可以减少 Shopee 接口慢、限流、失败对 C 端首页的影响。

## 5. 推荐实现方案（待实现）

### 5.1 数据同步

新增 Shopee AMS 高返佣商品同步任务，类似 TikTok Partner Campaign 商品同步：

```text
定时任务 -> productOfferV2(matchId, amsOffer=true, page, limit)
       -> 翻页直到 hasNextPage=false
       -> 标准化商品字段
       -> 入库缓存
```

建议缓存字段：

| 字段 | 说明 |
| --- | --- |
| `country_code` | 国家，例如 `ID`。 |
| `match_id` | Shopee 活动/商品池 ID。 |
| `list_type` | Shopee listType，暂时可空。 |
| `item_id` | Shopee 商品 ID。 |
| `shop_id` | Shopee 店铺 ID。 |
| `product_name` | 商品名。 |
| `image_url` | 商品图。 |
| `product_link` | Shopee 原商品 PDP。 |
| `offer_link` | Shopee 返回的 offer 链接。 |
| `price_min_minor` / `price_max_minor` | 价格区间，按 BeeX minor 单位存储。 |
| `commission_minor` | Shopee 返回的平台佣金金额，按 BeeX minor 单位存储。 |
| `commission_rate_bps` | 佣金率，建议统一转为 bps。 |
| `sales` | 销量。 |
| `period_start_time` / `period_end_time` | Offer 有效期。 |
| `raw_payload` | Shopee 原始返回，便于排查。 |
| `synced_at` | 同步时间。 |

### 5.2 C 端列表过滤

Shopee AMS 商品进入首页/推荐前，至少过滤：

| 过滤项 | 条件 |
| --- | --- |
| 无返佣 | `commission <= 0` 或 `commissionRate <= 0` |
| 无价格 | `priceMin/priceMax/price` 都为空或小于等于 0 |
| 无购买入口 | `productLink` 和 `offerLink` 都为空 |
| 无图片 | `imageUrl` 为空 |
| 低销量 | `sales <= 0`，后续可配置阈值 |
| Offer 过期 | 当前时间不在 `periodStartTime/periodEndTime` 内 |

## 6. App/H5 使用口径

### 6.1 首页高返佣 Tab

未来首页 `高返佣` Tab 可合并：

1. TikTok Partner Campaign 缓存商品。
2. Shopee AMS 缓存商品。

App/H5 不直接调用 Shopee，而是继续调用 BeeX：

```http
POST /api/v1/products/high-commission
```

示例：

```json
{
  "countryCode": "ID",
  "source": "PARTNER_CAMPAIGN",
  "limit": 20
}
```

后端内部可以把 Shopee AMS 商品统一映射为 BeeX 的高返佣来源，例如：

```text
source = SHOPEE_AMS
platform = SHOPEE
```

### 6.2 用户粘贴单个 Shopee 链接

用户粘贴 Shopee 商品链接时：

1. BeeX 解析 `shopId/itemId`。
2. 调 `productOfferV2(itemId, shopId)`。
3. 如果 Shopee 返回高佣金，直接按返回佣金计算用户可见返现。
4. 不强依赖缓存，但可以用缓存补图、补历史商品池标签。

## 7. 待确认问题

以下问题需要和 Shopee 运营或官方技术支持确认：

1. `matchId` 在 AMS 场景下的准确含义。
2. `listType` 的枚举值含义，尤其是为什么 `listType=1` 为空、`listType=2` 有数据。
3. `amsOffer=true` 是否代表 BeeX 账号下全部 AMS 高返佣商品。
4. Shopee 后台展示的 `approved` 商品数，和 API 分页总数如何对齐。
5. `productOfferV2` 是否有更推荐的分页方式：`page` 还是 `scrollId`。
6. `offerLink` 是否已经带 BeeX 账号归因，还是购买前仍必须调用 BeeX 的 Shopee 短链生成逻辑写入 tracking code。

## 8. 当前建议

短期先不把 Shopee AMS 列表缓存作为转链前置依赖：

- 单商品解析继续实时查 `productOfferV2(itemId/shopId)`。
- 如果返回高佣金，就按高佣金展示和计算。
- 首页高返佣列表再补缓存同步，用于推荐和运营筛选。

这样可以先保证用户粘贴高返佣 Shopee 商品链接时，BeeX 能及时展示正确返佣；后续再补“Shopee 高返佣推荐池”的完整运营能力。