# BeeX App 后端 API 接口文档

状态：v0.1  
适用端：BeeX App、App 内 H5、独立 H5  
源码依据：`seahub-x-service` 本地工程、`beex-app-h5/app/composables/useBeexApi.ts`  
不包含：第三方平台 Webhook、内部任务接口。管理后台接口仅记录 App/H5 依赖的配置能力，例如活动运营位配置。

## 1. 环境与通用约定

### 1.1 Base URL

| 环境 | Base URL |
| --- | --- |
| 印尼测试 | `https://api-id-test.beexofficial.com` |

App/H5 通过运行时配置注入 `apiBase`。不要在客户端代码里写死个人机器路径。

### 1.2 通用响应结构

所有 JSON API 统一返回：

```json
{
  "success": true,
  "message": "OK",
  "data": {}
}
```

客户端判断规则：

- `success=true`：读取 `data`。
- `success=false`：展示 `message`。
- HTTP `400`：参数错误、业务校验失败，例如不支持的商品平台。
- HTTP `404`：资源不存在，例如用户不存在。
- HTTP `5xx`：服务端异常或第三方平台异常。

### 1.3 通用枚举

```ts
type CountryCode = 'ID' | 'MY'
type Platform = 'TIKTOK' | 'SHOPEE' | 'LAZADA' | 'TRAVEL'
type UserRoleName = 'USER' | 'AGENT' | 'PARTNER'
type PaymentBizType = 'WALLET_TOP_UP' | 'COURSE_ORDER' | 'TRAVEL_ORDER' | 'SERVICE_FEE'
type PaymentOrderStatus = 'CREATED' | 'PENDING' | 'PAID' | 'EXPIRED' | 'FAILED' | 'CANCELLED'
```

### 1.4 当前鉴权口径

当前 H5 调用主要通过 `userId`、`countryCode`、设备信息传参，未统一接入 `Authorization: Bearer` 强校验。App 接入时仍应保存登录接口返回的 `accessToken`、`refreshToken`，后续服务端开启鉴权后统一加请求头。

### 1.5 接口归属标注规则

接口清单中的 `调用方` 用来说明接口主要由谁调用：

| 调用方 | 说明 |
| --- | --- |
| App | 原生 App 直接调用，通常用于登录、运行配置、日志、推送、系统能力。 |
| App 内 H5 | App WebView 内业务 H5 调用，当前主要是 `beex-app-h5`。 |
| 独立 H5 | 可在第三方浏览器打开的 H5 页面调用，例如分享承接页、邀请承接页。 |
| 管理后台 | 运营或管理后台调用，用于活动、规则、运行开关等配置。 |
| 三方回调 | Apple、TikTok 等外部平台回调到 BeeX 后端。 |
| 测试调试 | 仅测试环境或联调用，不应出现在生产用户链路。 |

一个接口可能服务多个调用方，文档按当前主要使用方标注；如果同一接口同时给 App 内 H5 和独立 H5 使用，会写成 `App 内 H5 / 独立 H5`。

## 2. 登录认证

### 2.1 获取登录方式

```http
GET /api/v1/auth/options?countryCode=ID&clientType=h5
```

响应 `data`：

```ts
type LoginOptionsResponse = {
  countryCode: CountryCode
  clientType: string
  methods: Array<{
    key: 'PHONE_ID' | 'WHATSAPP' | 'TIKTOK' | 'GOOGLE' | 'APPLE'
    enabled: boolean
    nativePreferred?: boolean
    clientId?: string
    reason?: string
  }>
}
```

### 2.2 WhatsApp 登录意图

```http
POST /api/v1/auth/whatsapp/login-intents
```

请求：

```json
{
  "countryCode": "ID",
  "clientType": "h5",
  "deviceId": "device_xxx",
  "returnUrl": "https://h5-id-test.beexofficial.com/auth?source=h5_whatsapp_login"
}
```

响应 `data`：

```ts
type LoginIntent = {
  loginIntentId: string
  loginCode: string
  expiresIn: number
  whatsappUrl: string
}
```

查询状态：

```http
GET /api/v1/auth/whatsapp/login-intents/{id}?consume=false
GET /api/v1/auth/whatsapp/login-intents/{id}?consume=true
POST /api/v1/auth/whatsapp/login-intents/{id}/consume
```

响应 `data`：

```ts
type LoginIntentStatus = {
  loginIntentId: string
  status: 'CREATED' | 'VERIFIED' | 'CONSUMED' | 'EXPIRED' | string
  userId?: string
  countryCode?: CountryCode
  displayName?: string
  whatsappNumber?: string
  referralCode?: string
  accessToken?: string
  refreshToken?: string
  expiresIn?: number
}
```

### 2.3 手机 OTP 登录

创建 OTP：

```http
POST /api/v1/auth/phone/otp-intents
```

请求：

```json
{
  "countryCode": "ID",
  "phoneNumber": "08123456789",
  "deviceId": "device_xxx",
  "clientType": "h5"
}
```

响应 `data`：

```ts
type PhoneOtpIntent = {
  otpIntentId: string
  expiresIn: number
  maskedPhone: string
  devCode?: string
}
```

验证 OTP：

```http
POST /api/v1/auth/phone/otp-intents/{otpIntentId}/verify
```

请求：

```json
{
  "code": "123456"
}
```

响应 `data`：

```ts
type ProviderLoginResponse = {
  userId: string
  countryCode: CountryCode
  newUser?: boolean
  provider: string
  providerUserId?: string
  displayName?: string
  avatarUrl?: string
  email?: string
  phoneNumber?: string
  referralCode?: string
  accessToken: string
  refreshToken: string
  expiresIn: number
}
```

### 2.4 TikTok 登录

创建授权 URL：

```http
GET /api/v1/auth/tiktok/auth-url?countryCode=ID&deviceId=device_xxx&returnUrl=https%3A%2F%2Fh5-id-test.beexofficial.com%2Fauth
```

响应 `data`：

```ts
type OAuthAuthorization = {
  authorizationUrl: string
  state: string
  redirectUri: string
  expiresIn: number
}
```

回调：

```http
GET /api/v1/auth/tiktok/callback?code=xxx&state=xxx
POST /api/v1/auth/tiktok/callback
```

POST 请求：

```json
{
  "code": "oauth_code",
  "state": "state_from_auth_url"
}
```

响应同 `ProviderLoginResponse`。

### 2.5 Google 登录

```http
POST /api/v1/auth/google/id-token
```

请求：

```json
{
  "countryCode": "ID",
  "deviceId": "device_xxx",
  "idToken": "google_id_token",
  "nonce": "optional_nonce"
}
```

响应同 `ProviderLoginResponse`。

## 3. 商品、转链与分享

### 3.1 高佣商品列表

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

请求：

```json
{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "keyword": "bag",
  "limit": 20
}
```

`platform` 可不传，表示混合搜索。

响应 `data`：

```ts
type ProductSearchResponse = {
  products: ProductItem[]
  warnings: string[]
}
```

### 3.2 解析商品链接

```http
POST /api/v1/products/resolve
```

请求：

```json
{
  "countryCode": "ID",
  "productUrl": "https://shop-id.tokopedia.com/view/product/1729618560920816365",
  "platformProductId": "1729618560920816365"
}
```

响应 `data`：

```ts
type ProductItem = {
  id: string
  platformProductId?: string
  name: string
  brand: string
  platform: Platform
  imageUrl?: string
  description?: string
  cashbackRate: number
  cashbackMinor?: number
  priceMinor: number
  currency?: string
  category?: string | null
  productUrl?: string
  offerUrl?: string
  source?: string
}
```

注意：

- 该接口只接受 TikTok/Tokopedia/Shopee 商品链接。
- BeeX 分享链接不能直接提交到该接口，否则会返回 `Unsupported product platform: OTHER`。
- App 首页粘贴 BeeX 分享链接时，应先解析 `shareCode` 并跳转分享承接页。

### 3.3 生成佣金链接或分享链接

```http
POST /api/v1/affiliate-links/generate
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "productUrl": "https://shop-id.tokopedia.com/view/product/1729618560920816365",
  "platformProductId": "1729618560920816365",
  "campaignId": "optional_campaign",
  "referralCode": "BEE123",
  "channel": "app",
  "deviceId": "device_xxx",
  "linkMode": "SHARE",
  "productName": "Product name",
  "imageUrl": "https://example.com/product.webp",
  "priceMinor": 83800000,
  "cashbackMinor": 10056000,
  "currency": "IDR",
  "couponId": "cpn_xxx"
}
```

响应 `data`：

```ts
type AffiliateLinkResult = {
  clickId: string
  platform: Platform
  originalUrl: string
  affiliateUrl: string
  purchaseUrl?: string
  shareUrl?: string
  shareCode?: string
  linkMode?: 'DIRECT' | 'SHARE'
  trackingTag: string
  note: string
}
```

说明：

- `linkMode=DIRECT`：只生成平台购买链接。
- `linkMode=SHARE`：同时生成 BeeX 分享链接，返回 `shareCode` 和 `shareUrl`。
- `couponId` 为可选字段；不传时订单完成后系统自动选择收益最高的可用购物返现券，传入时按用户指定券校验和核销，不可用时不静默替换为其他券。
- 当前 `affiliate_clicks` 记录的是生成转链时的点击/追踪记录，不等同于每个 B/C/D 访客打开分享页的访问记录。

### 3.4 获取分享详情

```http
GET /api/v1/affiliate-shares/{shareCode}
```

响应 `data`：

```ts
type AffiliateShareDetail = {
  shareCode: string
  shareUrl: string
  purchaseUrl: string
  platform: Platform
  productUrl: string
  productName?: string
  imageUrl?: string
  priceMinor?: number
  cashbackMinor?: number
  currency?: string
  shareUserId?: string
  referralCode?: string
}
```

### 3.5 记录分享页打开

```http
POST /api/v1/affiliate-shares/{shareCode}/clicks
```

请求：

```json
{
  "countryCode": "ID",
  "clickUserId": "usr_xxx",
  "channel": "app",
  "source": "share_landing",
  "deviceId": "device_xxx"
}
```

响应 `data`：

```ts
type AffiliateShareClickResponse = {
  bound: boolean
  reason:
    | 'BOUND_SUCCESS'
    | 'ALREADY_BOUND_TO_SAME_INVITER'
    | 'ALREADY_BOUND_TO_OTHER_INVITER'
    | 'SELF_INVITE_NOT_ALLOWED'
    | 'GUEST_CLICK_ONLY'
  shareUserId?: string | null
  clickUserId?: string | null
  parentUserId?: string | null
}
```

副作用：

- 始终写入 `share_clicks`，用于记录分享链接被打开。
- `BOUND_SUCCESS`：`clickUserId` 有值、不是分享人自己，且当前没有其他上级；服务端把点击用户绑定到该分享链接的 `shareUserId` 下。
- `ALREADY_BOUND_TO_SAME_INVITER`：点击用户已经绑定同一个邀请人，不重复写关系。
- `ALREADY_BOUND_TO_OTHER_INVITER`：点击用户已绑定其他上级，不覆盖既有 `referral_relation / referral_closure`，只保留本次 `share_clicks`。
- `SELF_INVITE_NOT_ALLOWED`：分享人打开自己的分享链接，不建立邀请关系。
- `GUEST_CLICK_ONLY`：游客打开或缺少可绑定用户信息，只记录点击，不建立邀请关系。

### 3.6 热门品牌

```http
GET /api/v1/popular-brands?countryCode=ID&limit=12&enabledOnly=true
```

响应 `data`：

```ts
type PopularBrandConfig = {
  id: string
  countryCode: CountryCode
  iconUrl?: string
  searchKeyword: string
  brandName: string
  description?: string
  cashbackBps: number
  sortOrder: number
  enabled: boolean
  createdAt?: string
  updatedAt?: string
}
```

### 3.7 商品推荐

用于商品详情页的更多推荐、同场景推荐等商品流。

```http
POST /api/v1/products/recommendations
```

请求：

```json
{
  "countryCode": "ID",
  "platform": "TIKTOK",
  "scene": "CATEGORY",
  "categoryName": "Storage Holders & Racks",
  "excludePlatformProductId": "1729618560920816365",
  "pageSize": 20
}
```

响应 `data`：

```ts
type ProductRecommendationResponse = {
  products: ProductItem[]
  pageInfo?: {
    hasMore: boolean
    nextCursor?: string
  }
  warnings: string[]
}
```

### 3.8 通用链接解析

用于只判断链接来源和商品平台，不直接返回完整商品详情。

```http
POST /api/v1/links/parse
```

请求：

```json
{
  "url": "https://shop-id.tokopedia.com/view/product/1729618560920816365"
}
```

响应 `data`：

```ts
type ParsedProductLink = {
  platform: Platform | 'OTHER'
  productUrl: string
  platformProductId?: string
  rawUrl?: string
}
```

### 3.9 Shopee 商品 Offer 查询

用于 Shopee Affiliate Open API 商品 Offer 调试或商品 Offer 查询。

```http
POST /api/v1/shopee/product-offers
```

请求体透传 Shopee Product Offer V2 查询参数，响应 `data` 为 Shopee 原始返回 JSON。

## 4. 用户资料

### 4.1 查询用户资料

```http
GET /api/v1/users/{userId}/profile
GET /api/v1/users/me?userId={userId}
GET /api/v1/users/current?userId={userId}
```

响应 `data`：

```ts
type UserProfile = {
  userId: string
  countryCode: CountryCode
  displayName: string
  phone?: string | null
  whatsappNumber?: string | null
  nickname?: string | null
  avatarUrl?: string | null
  referralCode?: string | null
  invitedByUserId?: string | null
  parentUserId?: string | null
  rootUserId?: string | null
  relationLevel?: number | null
  role?: UserRoleName
  starLevel?: number
  status?: string
  riskLevel?: string
  createdAt?: string
  updatedAt?: string
}
```

### 4.2 更新用户资料

```http
PUT /api/v1/users/{userId}/profile
```

请求：

```json
{
  "nickname": "BeeX User",
  "avatarUrl": "https://example.com/avatar.png"
}
```

响应同 `UserProfile`。

### 4.3 上传头像

```http
POST /api/v1/users/{userId}/avatar
Content-Type: multipart/form-data
```

字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | file | 是 | 头像文件 |

响应同 `UserProfile`。

## 5. 成长、角色与关系树

### 5.1 查询用户角色

```http
GET /api/v1/growth/users/{userId}/role
```

响应 `data`：

```ts
type UserRoleModel = {
  userId: string
  countryCode: CountryCode
  role: UserRoleName
  starLevel: number
  status: string
  effectiveAt?: string
  updatedAt?: string
}
```

当前实现是单字段 `starLevel`。目标业务模型里的 `agent_star`、`partner_star` 尚未在 App 接口中拆分。

### 5.2 查询邀请关系

```http
GET /api/v1/growth/users/{userId}/relation
```

响应 `data`：

```ts
type ReferralRelationModel = {
  id: string
  countryCode: CountryCode
  userId: string
  parentUserId?: string | null
  rootUserId?: string | null
  level: number
  path?: string | null
  status: string
  createdAt?: string
  updatedAt?: string
}
```

### 5.3 查询团队树

```http
GET /api/v1/growth/users/{userId}/tree?maxDepth=20&limit=100
```

响应 `data`：

```ts
type TeamTreeResponse = {
  summary: {
    rootUserId: string
    maxDepth: number
    totalMembers: number
    userCount: number
    agentCount: number
    partnerCount: number
  }
  members: Array<{
    countryCode: CountryCode
    userId: string
    parentUserId?: string | null
    rootUserId?: string | null
    relationLevel: number
    depth: number
    path?: string | null
    nickname?: string | null
    whatsappNumber?: string | null
    referralCode?: string | null
    role: UserRoleName
    starLevel: number
    userStatus: string
    joinedAt?: string
  }>
}
```

### 5.4 我的推广联盟总览

用于 App/H5「我的推广联盟」页面。该接口一次返回当前页所需的汇总数据和分页成员列表，成员列表支持按角色、星级分页筛选。

```http
GET /api/v1/growth/users/{userId}/network-overview?maxDepth=20&limit=20&offset=0&role=AGENT&starLevel=1
```

Query 参数：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `maxDepth` | number | 否 | 查询下级层级，默认 `20`。 |
| `limit` | number | 否 | 本页数量，默认 `20`。 |
| `offset` | number | 否 | 分页偏移，默认 `0`。 |
| `role` | `USER \| AGENT \| PARTNER` | 否 | 成员角色筛选；不传表示全部角色。 |
| `starLevel` | number | 否 | 星级筛选；通常与 `role=AGENT/PARTNER` 一起使用。 |

响应 `data`：

```ts
type NetworkOverview = {
  summary: {
    rootUserId: string
    maxDepth: number
    totalMembers: number
    estimatedIncomeMinor: number
    actualIncomeMinor: number
    salesCommissionMinor: number
    totalCashbackMinor: number
    userCount: number
    agentCount: number
    partnerCount: number
    agentStarCounts: Record<string, number>
    partnerStarCounts: Record<string, number>
  }
  members: Array<{
    countryCode: CountryCode
    userId: string
    parentUserId?: string | null
    rootUserId?: string | null
    relationLevel: number
    depth: number
    path?: string | null
    nickname?: string | null
    whatsappNumber?: string | null
    avatarUrl?: string | null
    referralCode?: string | null
    role: UserRoleName
    starLevel: number
    userStatus: string
    joinedAt?: string
    estimatedCashbackMinor: number
    settledCashbackMinor: number
  }>
}
```

统计口径：

- `estimatedIncomeMinor`：当前用户从推广联盟成员产生的预估收益，排除 `INVALID` 佣金。
- `actualIncomeMinor`：当前用户从推广联盟成员产生的已到账/可提现收益，统计 `AVAILABLE`、`PAID` 佣金。
- `salesCommissionMinor`：排除 `USER_CASHBACK` 后的销售类佣金。
- `totalCashbackMinor`：`USER_CASHBACK` 类型返现。
- 成员级 `estimatedCashbackMinor`、`settledCashbackMinor` 按该成员作为 `sourceUserId` 聚合。

### 5.4.1 上级成员

```http
GET /api/v1/growth/users/{userId}/ancestors?maxDepth=20
```

响应 `data` 为 `ReferralAncestorModel[]`。

### 5.4.2 直属下级

```http
GET /api/v1/growth/users/{userId}/children?limit=50&offset=0
```

响应 `data` 为 `TeamMemberModel[]`。

### 5.4.3 下级成员

```http
GET /api/v1/growth/users/{userId}/descendants?maxDepth=20&limit=100&offset=0
```

响应 `data` 为 `TeamMemberModel[]`。

### 5.4.4 下级成员收益

用于列表中展示成员带来的预估推广返现和已到账返现。

```http
GET /api/v1/growth/users/{userId}/children-earnings?maxDepth=1&limit=100&offset=0
```

响应 `data`：

```ts
type ChildEarningResponse = {
  member: TeamMemberModel
  estimatedRebateMinor: number
  settledRebateMinor: number
}
```

### 5.4.5 团队汇总

```http
GET /api/v1/growth/users/{userId}/team-summary?maxDepth=20
```

响应 `data` 为 `TeamSummaryModel`。

### 5.5 邀请码预览

```http
GET /api/v1/growth/invites/{referralCode}/preview?countryCode=ID&userId=usr_xxx&courseAmountMinor=100000
```

H5 邀请入口使用同一个邀请码生成承接链接，不新增后端接口：

```text
/invite/{referralCode}?ref={referralCode}&inviterUserId={userId}&countryCode=ID&targetRole=AGENT
```

- `targetRole=USER`：承接页展示“信用返现奖励”福利页，保存邀请码上下文，引导登录/注册。
- `targetRole=AGENT|PARTNER`：承接页展示“BeeX-团长”权益页，默认选中对应 Agent/Partner tab；登录后跳转 `/membership?upgrade=1&inviteCode={referralCode}&targetRole={targetRole}`，升级弹窗预填邀请码并继续调用本节 preview 接口和 `POST /api/v1/course-orders`。
- 当前 H5 登录接口没有独立消费邀请码字段；普通 User 注册后的关系绑定不能只靠前端完成，需要登录或绑定接口支持后才能做到 100% 自动归因。

响应 `data`：

```ts
type InvitePreview = {
  referralCode: string
  valid: boolean
  discountEligible: boolean
  inviterUserId?: string | null
  inviterName?: string | null
  inviterRole?: UserRoleName | string | null
  inviterStarLevel: number
  inviterParentUserId?: string | null
  inviteeDiscountBps: number
  inviteeDiscountMinor: number
  payableAmountMinor: number
  directRewardBps: number
  directRewardAmountMinor: number
  indirectRewardBps: number
  indirectRewardAmountMinor: number
  reason: string
}
```

常见 `reason`：

| reason | 含义 |
| --- | --- |
| `OK` | 可用 |
| `SELF_INVITE_NOT_ALLOWED` | 不能使用自己的邀请码 |
| `USER_ALREADY_BOUND_TO_ANOTHER_INVITER` | 用户已绑定其他邀请人 |

### 5.6 免费升级 Partner

查询当前 Agent 是否满足免费升级 Partner 条件：

```http
GET /api/v1/growth/users/{userId}/free-partner-upgrade
```

响应 `data`：

```ts
type FreePartnerUpgradeStatus = {
  userId: string
  eligible: boolean
}
```

领取免费升级：

```http
POST /api/v1/growth/users/{userId}/free-partner-upgrade
```

响应 `data` 同 `UserRoleModel`。

### 5.7 更新用户角色

```http
POST /api/v1/growth/users/{userId}/role
```

请求：

```json
{
  "countryCode": "ID",
  "role": "AGENT",
  "starLevel": 1,
  "reason": "MANUAL_ADJUST",
  "operator": "system"
}
```

响应 `data` 同 `UserRoleModel`。

### 5.8 绑定邀请关系

```http
POST /api/v1/growth/relations/bind
```

用于服务端确认用户关系归属后绑定邀请关系。前端不要绕过服务端规则自行伪造关系。

## 6. 收益、钱包与提现

### 6.1 收益汇总

```http
GET /api/v1/earnings/{userId}/summary
```

响应 `data`：

```ts
type EarningsSummary = {
  wallet: WalletModel | null
  orderStats: {
    totalOrders: number
    pendingOrders: number
    completedOrders: number
    cancelledOrders: number
    grossAmountMinor: number
    cashbackMinor: number
  }
  commissionStats: {
    totalRecords: number
    totalCommissionMinor: number
    pendingCommissionMinor: number
    availableCommissionMinor: number
    frozenCommissionMinor: number
    paidCommissionMinor: number
    invalidCommissionMinor: number
  }
}
```

### 6.2 最近订单

```http
GET /api/v1/earnings/{userId}/orders?limit=20
```

响应 `data`：

```ts
type AffiliateOrder = {
  id: string
  countryCode: CountryCode
  platform: Platform
  platformOrderId: string
  clickId?: string
  userId: string
  currency: string
  grossAmountMinor: number
  cashbackMinor: number
  productName?: string
  imageUrl?: string
  productUrl?: string
  priceMinor?: number
  status: string
  commissionStatus?: string
  orderedAt?: string
  settledAt?: string
  releaseAt?: string
  rawPayload?: string
}
```

商品展示字段来自生成分享/转链时保存的商品快照，即 `share_logs.target_url`，通过 `affiliate_orders.click_id` 关联；`rawPayload` 仍保留平台原始订单 payload，不承载 BeeX 自定义商品图字段。

### 6.2.1 佣金明细

```http
GET /api/v1/earnings/{userId}/commissions?limit=50
```

响应 `data` 为 `CommissionRecord[]`。

### 6.3 订单追踪

```http
GET /api/v1/order-tracking/users/{userId}?limit=100
```

响应 `data`：

```ts
type OrderTrackingRecord = {
  clickId: string
  countryCode: CountryCode
  platform: Platform
  userId: string
  productUrl?: string
  affiliateUrl?: string
  trackingTag?: string
  clickedAt?: string
  orderId?: string
  platformOrderId?: string
  orderStatus?: string
  commissionStatus?: string
  orderedAt?: string
  releaseAt?: string
  currency?: string
  grossAmountMinor?: number
  cashbackMinor?: number
  productName?: string
  imageUrl?: string
  priceMinor?: number
  trackingStatus?: 'TRACKING' | 'SUCCESS' | 'MISSING' | string
}
```

### 6.4 返现问题申诉

返现问题申诉使用专用业务接口，不使用 `POST /api/v1/app-logs/feedback`。App log feedback 只用于日志反馈，不承载订单号、购买时间、申诉状态等业务字段。

上传申诉截图：

```http
POST /api/v1/cashback-appeals/attachments?countryCode=ID&userId=usr_xxx
Content-Type: multipart/form-data
```

表单字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `file` | File | 是 | 截图图片，支持 `jpeg`、`png`、`webp`、`gif`，最大 10MB |

响应 `data`：

```ts
type CashbackAppealAttachmentResponse = {
  fileUrl: string
  fileType: 'IMAGE' | string
}
```

如果客户端要直接上传 OSS，可先获取上传凭证：

```http
POST /api/v1/cashback-appeals/upload-token?countryCode=ID&userId=usr_xxx&fileName=order.png
```

响应结构同 App 日志上传凭证，但对象目录固定在 `cashback-appeals/{country}/{date}/{userId}/`。

提交申诉：

```http
POST /api/v1/cashback-appeals
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "platform": "TIKTOK",
  "purchasedAt": "2026-06-01T18:30:00",
  "platformOrderId": "123456789",
  "whatsappNumber": "812345678",
  "description": "订单已完成但未到账",
  "attachmentUrls": [
    "https://beex-id-test-h5.oss-ap-southeast-5.aliyuncs.com/cashback-appeals/id/2026-06-01/usr_xxx/appeal_xxx.png"
  ]
}
```

响应 `data`：

```ts
type CashbackAppealResponse = {
  id: string
  status: 'SUBMITTED' | string
  createdAt: string
}
```

落库：

- `cashback_claims`：申诉主记录，`claim_status` 初始为 `SUBMITTED`。
- `claim_attachments`：申诉截图 URL。

### 6.5 钱包详情

```http
GET /api/v1/wallets/{userId}
```

响应 `data`：

```ts
type WalletModel = {
  userId: string
  countryCode: CountryCode
  currency: string
  pendingBalanceMinor: number
  availableBalanceMinor: number
  frozenBalanceMinor: number
  riskHoldBalanceMinor: number
  totalEarnedMinor: number
  totalWithdrawnMinor: number
  updatedAt?: string
}
```

### 6.5.1 提现记录

```http
GET /api/v1/withdraw/records?userId=usr_xxx&limit=50&offset=0
```

响应 `data`：

```ts
type WithdrawRecord = {
  id: string
  countryCode: CountryCode
  userId: string
  amountMinor: number
  feeMinor: number
  currency: string
  status: string
  payoutProvider?: string
  rejectReason?: string | null
  createdAt?: string
  updatedAt?: string
}
```

### 6.6 提现资料

查询：

```http
GET /api/v1/withdraw/payout-profile?userId=usr_xxx
```

响应 `data` 为 `PayoutProfile[]`。同一用户可存在多个收款方式，H5 按 `payoutProvider` 选择 `BANK` 或 `EWALLET`；未配置时返回空数组。

保存：

```http
POST /api/v1/withdraw/payout-profile
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "fullName": "User Name",
  "idType": "ID_CARD",
  "idNumber": "123456",
  "payoutProvider": "BANK",
  "bankName": "BCA",
  "bankAccountNumber": "1234567890",
  "bankAccountHolderName": "User Name"
}
```

响应 `data`：

```ts
type PayoutProfile = {
  id: string
  countryCode: CountryCode
  userId: string
  fullName: string
  idType: string
  idNumber: string
  payoutProvider: string
  bankName: string
  bankAccountNumber: string
  bankAccountHolderName: string
  status: string
  rejectReason?: string | null
}
```

### 6.7 申请提现

```http
POST /api/v1/withdraw/apply
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "amountMinor": 100000,
  "feeMinor": 0,
  "payoutProvider": "BANK"
}
```

响应 `data`：

```ts
type ApplyWithdrawResponse = {
  withdrawId: string
  status: string
}
```

## 7. 课程、升级与支付

### 7.1 创建课程/升级订单

```http
POST /api/v1/course-orders
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "courseCode": "AGENT_STARTER",
  "courseName": "Agent Starter",
  "amountMinor": 100000,
  "roleAfterPaid": "AGENT",
  "starAfterPaid": 1,
  "inviteReferralCode": "BEE123",
  "couponId": "cpn_xxx",
  "successRedirectUrl": "https://h5-id-test.beexofficial.com/payment-success.html",
  "failureRedirectUrl": "https://h5-id-test.beexofficial.com/payment-failed.html"
}
```

响应 `data`：

```ts
type CourseOrderPaymentResponse = {
  courseOrder: CourseOrder
  payment: PaymentResponse
}
```

### 7.2 查询课程订单

```http
GET /api/v1/course-orders/{id}
GET /api/v1/course-orders?userId=usr_xxx&limit=20
```

响应 `data` 为单个 `CourseOrder` 或 `CourseOrder[]`。

### 7.3 创建通用支付单

```http
POST /api/v1/payments/create
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "bizType": "WALLET_TOP_UP",
  "bizId": "optional_biz_id",
  "amountMinor": 100000,
  "description": "Wallet top up",
  "successRedirectUrl": "https://h5-id-test.beexofficial.com/payment-success.html",
  "failureRedirectUrl": "https://h5-id-test.beexofficial.com/payment-failed.html"
}
```

响应 `data`：

```ts
type PaymentResponse = {
  paymentOrderId: string
  externalId: string
  bizType: PaymentBizType
  provider: 'MOCK' | 'XENDIT'
  providerPaymentId?: string
  currency: string
  amountMinor: number
  feeMinor: number
  status: PaymentOrderStatus
  checkoutUrl?: string
}
```

### 7.4 查询支付单

```http
GET /api/v1/payments/{id}
```

响应同 `PaymentResponse`。

### 7.5 模拟支付成功

```http
POST /api/v1/payments/{id}/mock-paid
```

仅测试环境使用。切换真实支付 provider 后，该接口会被拒绝。

## 8. 券、活动与奖励

### 8.1 用户券列表

```http
GET /api/v1/coupons?userId=usr_xxx&limit=50
```

响应 `data`：

```ts
type UserCoupon = {
  id: string
  countryCode: CountryCode
  userId: string
  couponType: string
  title: string
  factorBps: number
  amountMinor: number
  currency?: string
  status: string
  expiresAt?: string
  sourceType?: string
  sourceId?: string
}
```

### 8.1.1 查询单张券

```http
GET /api/v1/coupons/{id}
```

响应 `data` 同 `UserCoupon`。

### 8.1.2 发放券

```http
POST /api/v1/coupons/issue
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "couponType": "USER_DISCOUNT",
  "rewardMode": "DISCOUNT",
  "claimMode": "AUTO",
  "title": "用户优惠券",
  "factorBps": 0,
  "amountMinor": 500000,
  "minOrderMinor": 3000000,
  "maxDiscountMinor": 0,
  "currency": "IDR",
  "expiresAt": "2027-01-01T00:59:59",
  "sourceType": "CAMPAIGN",
  "sourceId": "acm_xxx"
}
```

响应 `data` 同 `UserCoupon`。

### 8.1.3 领取券

```http
POST /api/v1/coupons/{id}/claim
```

请求：

```json
{
  "userId": "usr_xxx",
  "sourceType": "CAMPAIGN",
  "sourceId": "acm_xxx"
}
```

响应 `data`：

```ts
type ClaimCouponResponse = {
  success: boolean
}
```

### 8.1.4 核销券

```http
POST /api/v1/coupons/{id}/use
```

请求：

```json
{
  "sourceType": "AFFILIATE_ORDER",
  "sourceId": "ord_xxx"
}
```

响应 `data`：

```ts
type UseCouponResponse = {
  success: boolean
}
```

### 8.1.5 取消券

```http
POST /api/v1/coupons/{id}/cancel
```

请求：

```json
{
  "sourceType": "ADMIN",
  "sourceId": "manual_cancel"
}
```

响应 `data`：

```ts
type CancelCouponResponse = {
  success: boolean
}
```

### 8.1.6 预览券优惠

用于下单或升级前预览某张券对实付金额、返现奖励的影响。

```http
POST /api/v1/coupons/preview
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "bizType": "AFFILIATE_ORDER",
  "amountMinor": 83800000,
  "couponId": "cpn_xxx"
}
```

响应 `data` 以后端 `CouponPreviewResponse` 为准。

### 8.1.7 过期券

```http
POST /api/v1/coupons/expire
```

用于将已过期但仍处于可用状态的券批量标记为过期。

响应 `data`：

```ts
type ExpireCouponResponse = {
  count: number
}
```

### 8.2 活动卡片

```http
GET /api/v1/activity-campaigns/cards?countryCode=ID&userId=usr_xxx
```

响应 `data`：

```ts
type ActivityCampaignCard = {
  campaignId: string
  campaignCode: string
  title: string
  subtitle?: string
  description?: string
  cardImageUrl?: string
  cardTheme?: string
  targetRoles?: string
  newUserOnly: boolean
  priority: number
  effectiveFrom: string
  effectiveTo?: string
  rules: Array<{
    ruleId: string
    triggerEvent: string
    platform?: Platform
    orderNo: number
    minGmvMinor: number
    rewardType: string
    rewardAmountMinor: number
    rewardBps: number
    currency: string
    achieved: boolean
    issued: boolean
    issuedRewardMinor: number
  }>
}
```

### 8.2.1 活动展示位配置

用于首页 Banner、活动弹窗、悬浮入口等可配置运营位。前端按展示位批量查询，由后端按国家、角色、人群、档期、启用状态和优先级过滤后返回。

```http
GET /api/v1/campaigns/placements?countryCode=ID&placements=HOME_BANNER,HOME_POPUP,HOME_FLOATING_ENTRY&userId=usr_xxx&role=USER&environmentId=id-test
```

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码，例如 `ID`。 |
| Query | `placements` | string | 是 | 逗号分隔展示位。当前首页使用 `HOME_BANNER,HOME_POPUP,HOME_FLOATING_ENTRY`。 |
| Query | `userId` | string | 否 | 当前用户 ID，未登录时不传。 |
| Query | `role` | string | 否 | 当前用户角色：`USER`、`AGENT`、`PARTNER`。 |
| Query | `appVersion` | string | 否 | App 版本，用于版本定向。 |
| Query | `environmentId` | string | 否 | 环境 ID，用于环境定向，例如 `id-test`。 |

响应 `data`：

```ts
type CampaignPlacementCode =
  | 'HOME_BANNER'
  | 'HOME_POPUP'
  | 'HOME_FLOATING_ENTRY'
  | 'PRODUCT_DETAIL_CARD'
  | 'COUPON_ENTRY'
  | 'PROFILE_BANNER'
  | 'WITHDRAW_SUCCESS'

type CampaignPlacement = {
  id: string
  countryCode: CountryCode
  name: string
  placement: CampaignPlacementCode
  status: 'DRAFT' | 'ACTIVE' | 'DISABLED'
  priority: number
  startAt: string
  endAt?: string
  audienceRule?: {
    loginRequired?: boolean
    roles?: Array<'USER' | 'AGENT' | 'PARTNER'>
    newUserOnly?: boolean
    minAppVersion?: string
    maxAppVersion?: string
  }
  content: {
    title?: string
    subtitle?: string
    description?: string
    imageUrl?: string
    iconUrl?: string
    buttonText?: string
    backgroundColor?: string
  }
  action: {
    type: 'ROUTE' | 'PRODUCT' | 'EXTERNAL_URL' | 'CLAIM_COUPON' | 'SHARE'
    target: string
  }
  frequencyRule?: {
    mode: 'EVERY_TIME' | 'ONCE_PER_DAY' | 'ONCE_PER_CAMPAIGN'
    dismissTtlHours?: number
  }
}

type CampaignPlacementsResponse = {
  placements: Partial<Record<CampaignPlacementCode, CampaignPlacement[]>>
}
```

响应示例：

```json
{
  "success": true,
  "message": "OK",
  "data": {
    "placements": {
      "HOME_BANNER": [
        {
          "id": "cpl_home_banner_001",
          "countryCode": "ID",
          "name": "新用户首单活动",
          "placement": "HOME_BANNER",
          "status": "ACTIVE",
          "priority": 10,
          "startAt": "2026-06-01T00:00:00+07:00",
          "endAt": "2026-06-30T23:59:59+07:00",
          "audienceRule": {
            "roles": ["USER"],
            "newUserOnly": true
          },
          "content": {
            "title": "首单立返",
            "subtitle": "复制商品链接，查询返利再下单",
            "imageUrl": "https://cdn.example.com/campaign/home-banner.png",
            "buttonText": "查看活动"
          },
          "action": {
            "type": "ROUTE",
            "target": "/coupons"
          },
          "frequencyRule": {
            "mode": "EVERY_TIME"
          }
        }
      ],
      "HOME_POPUP": [],
      "HOME_FLOATING_ENTRY": []
    }
  }
}
```

### 8.2.2 管理后台活动展示位配置

用于管理后台配置首页 Banner、活动弹窗、悬浮入口等活动坑位。后台配置完成后，前台通过 `GET /api/v1/campaigns/placements` 查询命中配置。

#### 查询活动展示位列表

```http
GET /api/v1/admin/campaign-placements?countryCode=ID&placement=HOME_BANNER&status=ACTIVE&pageNo=1&pageSize=20
```

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码。 |
| Query | `placement` | string | 否 | 展示位，例如 `HOME_BANNER`。 |
| Query | `status` | string | 否 | `DRAFT`、`ACTIVE`、`DISABLED`。 |
| Query | `keyword` | string | 否 | 按名称搜索。 |
| Query | `pageNo` | number | 否 | 页码，默认 1。 |
| Query | `pageSize` | number | 否 | 每页数量，默认 20。 |

响应 `data`：

```ts
type AdminCampaignPlacementPage = {
  records: CampaignPlacement[]
  pageNo: number
  pageSize: number
  total: number
}
```

#### 查询单个活动展示位

```http
GET /api/v1/admin/campaign-placements/{id}
```

响应 `data`：`CampaignPlacement`。

#### 创建活动展示位

```http
POST /api/v1/admin/campaign-placements
```

请求：

```ts
type AdminCampaignPlacementRequest = {
  countryCode: CountryCode
  name: string
  placement: CampaignPlacementCode
  status?: 'DRAFT' | 'ACTIVE' | 'DISABLED'
  priority: number
  startAt: string
  endAt?: string
  audienceRule?: {
    loginRequired?: boolean
    roles?: Array<'USER' | 'AGENT' | 'PARTNER'>
    newUserOnly?: boolean
    minAppVersion?: string
    maxAppVersion?: string
  }
  content: {
    title?: string
    subtitle?: string
    description?: string
    imageUrl?: string
    iconUrl?: string
    buttonText?: string
    backgroundColor?: string
  }
  action: {
    type: 'ROUTE' | 'PRODUCT' | 'EXTERNAL_URL' | 'CLAIM_COUPON' | 'SHARE'
    target: string
  }
  frequencyRule?: {
    mode: 'EVERY_TIME' | 'ONCE_PER_DAY' | 'ONCE_PER_CAMPAIGN'
    dismissTtlHours?: number
  }
}
```

响应 `data`：`CampaignPlacement`。

#### 更新活动展示位

```http
PUT /api/v1/admin/campaign-placements/{id}
```

请求 `body` 同 `AdminCampaignPlacementRequest`，响应 `data` 为更新后的 `CampaignPlacement`。

#### 启用 / 停用活动展示位

```http
POST /api/v1/admin/campaign-placements/{id}/enable
POST /api/v1/admin/campaign-placements/{id}/disable
```

响应 `data`：

```ts
type AdminCampaignPlacementStatusResponse = {
  updated: boolean
}
```

#### 删除活动展示位

```http
DELETE /api/v1/admin/campaign-placements/{id}
```

响应 `data`：

```ts
type AdminCampaignPlacementDeleteResponse = {
  deleted: boolean
}
```

#### 查询后台配置选项

```http
GET /api/v1/admin/campaign-placements/options
```

响应 `data`：

```ts
type CampaignPlacementOptions = {
  placements: CampaignPlacementCode[]
  statuses: Array<'DRAFT' | 'ACTIVE' | 'DISABLED'>
}
```

#### 预览活动展示位命中结果

```http
POST /api/v1/admin/campaign-placements/{id}/preview
```

请求：

```json
{
  "userId": "usr_xxx",
  "role": "USER",
  "countryCode": "ID",
  "platform": "H5",
  "appVersion": "88.88.88"
}
```

响应 `data`：

```ts
type CampaignPlacementPreviewResponse = {
  matched: boolean
  reason?: string
  placement?: CampaignPlacement
}
```

### 8.3 TPB 奖励

```http
GET /api/v1/tpb-rewards?userId=usr_xxx&limit=12
```

响应 `data`：

```ts
type TpbReward = {
  id: string
  countryCode: CountryCode
  userId: string
  statMonth: string
  baseAmountMinor: number
  multiplierBps: number
  rewardAmountMinor: number
  status: string
}
```

### 8.4 活动奖励记录

```http
GET /api/v1/activity-campaigns/rewards?userId=usr_xxx&limit=50
```

响应 `data` 为 `ActivityRewardRecord[]`。

### 8.5 TPB 奖励计算

```http
POST /api/v1/tpb-rewards/calculate
```

请求：

```json
{
  "countryCode": "ID",
  "userId": "usr_xxx",
  "statMonth": "2026-06",
  "baseAmountMinor": 100000,
  "multiplierBps": 10000
}
```

响应 `data` 同 `TpbReward`。

## 9. App 配置、日志与推送

### 9.1 国家列表

```http
GET /api/v1/countries
```

用于 App 初始化国家选择。

### 9.2 App 运行时配置

```http
GET /api/v1/app/runtime-config?countryCode=ID&platform=ANDROID
```

用于下发客户端运行时配置。具体字段以后端返回为准。

### 9.3 App 日志上传凭证

```http
GET /api/v1/app-logs/upload-token?countryCode=ID&userId=usr_xxx
GET /api/v1/app-logs/sls-token?countryCode=ID&userId=usr_xxx
POST /api/v1/app-logs/feedback
```

当前线上日志未上传到 SLS 时，App 仍可先保留接口封装，避免后续接入时改业务代码。

### 9.4 推送设备

```http
POST /api/v1/push/devices/register
POST /api/v1/push/devices/disable
GET  /api/v1/push/devices?userId=usr_xxx
```

推送通知接口：

```http
POST /api/v1/push/notifications/users
GET  /api/v1/push/tasks/{taskId}
```

### 9.5 Apple 登录

```http
POST /api/v1/auth/apple/native
POST /api/v1/auth/apple/callback
GET /api/v1/auth/apple/callback
POST /api/v1/auth/apple/android-callback
```

用于 iOS 原生 Apple 登录、Web callback 和 Android Sign in with Apple callback 承接。

### 9.6 TikTok 平台账号集成

```http
GET /api/v1/integrations/tiktok/auth-url
GET /api/v1/integrations/tiktok/callback
POST /api/v1/integrations/tiktok/accounts/{platformAccountId}/refresh
```

这是平台账号授权和刷新接口，不等同于用户登录接口 `/api/v1/auth/tiktok/*`。

## 10. App 接入注意事项

1. 首页输入框必须先判断 BeeX 分享链接，再判断平台商品链接。
2. BeeX 分享链接走 `/api/v1/affiliate-shares/{shareCode}`，不要送到 `/api/v1/products/resolve`。
3. 所有金额字段 `amountMinor`、`priceMinor`、`cashbackMinor` 都是最小货币单位。
4. 角色当前为 `role + starLevel` 单星级模型，App 不要提前假设存在 `agentStar`、`partnerStar` 字段。
5. 当前 H5 通过 `userId` 传递用户身份；App 应保留 token 存储与请求头扩展位。
6. `mock-paid` 只能用于测试环境。
7. 上传头像使用 `multipart/form-data`，字段名必须是 `file`。

## 11. 接口归属总览

本节按 `业务域 + 调用方 + 使用场景` 标注接口归属。App、App 内 H5、独立 H5、三方回调和测试调试接口看本节；管理后台配置接口另见 11.1；字段详情见第 13 节。

| 业务域 | 调用方 | 方法 | 路径 | 使用场景 |
| --- | --- | --- | --- | --- |
| 登录认证 | App 内 H5 / 独立 H5 | GET | `/api/v1/auth/options` | 登录页查询当前国家和端可用登录方式。 |
| 登录认证 | App 内 H5 / 独立 H5 | POST | `/api/v1/auth/whatsapp/login-intents` | 创建 WhatsApp 登录意图。 |
| 登录认证 | App 内 H5 / 独立 H5 | GET | `/api/v1/auth/whatsapp/login-intents/{id}` | 轮询 WhatsApp 登录状态。 |
| 登录认证 | App 内 H5 / 独立 H5 | POST | `/api/v1/auth/whatsapp/login-intents/{id}/consume` | 消费 WhatsApp 登录结果并换 token。 |
| 登录认证 | App 内 H5 / 独立 H5 | POST | `/api/v1/auth/phone/otp-intents` | 创建手机 OTP 登录意图。 |
| 登录认证 | App 内 H5 / 独立 H5 | POST | `/api/v1/auth/phone/otp-intents/{otpIntentId}/verify` | 校验 OTP 并完成登录。 |
| 登录认证 | App 内 H5 / 独立 H5 | GET | `/api/v1/auth/tiktok/auth-url` | 创建 TikTok 用户登录授权链接。 |
| 登录认证 | App 内 H5 / 独立 H5 | POST | `/api/v1/auth/tiktok/callback` | H5 用 TikTok OAuth code 完成登录。 |
| 登录认证 | App 内 H5 / 独立 H5 | POST | `/api/v1/auth/google/id-token` | Google 登录换取 BeeX token。 |
| 登录认证 | App | POST | `/api/v1/auth/apple/native` | iOS 原生 Apple 登录。 |
| 登录认证 | 三方回调 | POST | `/api/v1/auth/apple/callback` | Apple Web 登录表单回调。 |
| 登录认证 | 三方回调 | GET | `/api/v1/auth/apple/callback` | Apple Web 登录 GET 兼容回调。 |
| 登录认证 | 三方回调 | POST | `/api/v1/auth/apple/android-callback` | Android Sign in with Apple Web 回调。 |
| 商品与转链 | App 内 H5 | POST | `/api/v1/products/high-commission` | 首页和商品池查询高返佣商品。 |
| 商品与转链 | App 内 H5 / 独立 H5 | POST | `/api/v1/products/resolve` | 解析三方商品链接，进入商品详情页。 |
| 商品与转链 | App 内 H5 | POST | `/api/v1/products/recommendations` | 商品详情页推荐商品。 |
| 商品与转链 | App 内 H5 | POST | `/api/v1/links/parse` | 首页粘贴/剪贴板链接轻量识别。 |
| 商品与转链 | App 内 H5 | POST | `/api/v1/shopee/product-offers` | Shopee 商品 Offer 查询和调试。 |
| 商品与转链 | App 内 H5 | GET | `/api/v1/popular-brands` | 首页热门品牌入口。 |
| 商品分享 | App 内 H5 | POST | `/api/v1/affiliate-links/generate` | 商品详情页生成购买链接或 BeeX 分享链接。 |
| 商品分享 | 独立 H5 / App 内 H5 | GET | `/api/v1/affiliate-shares/{shareCode}` | 分享承接页查询分享详情；App 首页识别 BeeX 分享链接。 |
| 商品分享 | 独立 H5 | POST | `/api/v1/affiliate-shares/{shareCode}/clicks` | 分享承接页打开后记录点击和邀请关系。 |
| 收益订单 | App 内 H5 | GET | `/api/v1/earnings/{userId}/summary` | 收益首页汇总。 |
| 收益订单 | App 内 H5 | GET | `/api/v1/earnings/{userId}/orders` | 我的订单列表。 |
| 收益订单 | App 内 H5 | GET | `/api/v1/earnings/{userId}/commissions` | 佣金明细列表。 |
| 收益订单 | App 内 H5 | GET | `/api/v1/order-tracking/users/{userId}` | 订单追踪页。 |
| 钱包提现 | App 内 H5 | GET | `/api/v1/wallets/{userId}` | 钱包余额和可提现金额。 |
| 钱包提现 | App 内 H5 | GET | `/api/v1/withdraw/records` | 提现记录列表。 |
| 钱包提现 | App 内 H5 | GET | `/api/v1/withdraw/payout-profile` | 查询提现收款资料。 |
| 钱包提现 | App 内 H5 | POST | `/api/v1/withdraw/payout-profile` | 保存提现收款资料。 |
| 钱包提现 | App 内 H5 | POST | `/api/v1/withdraw/apply` | 发起提现申请。 |
| 用户资料 | App 内 H5 / App | GET | `/api/v1/users/{userId}/profile` | 我的页、资料页查询用户资料。 |
| 用户资料 | App 内 H5 / App | PUT | `/api/v1/users/{userId}/profile` | 修改用户资料。 |
| 用户资料 | App 内 H5 / App | POST | `/api/v1/users/{userId}/avatar` | 上传头像。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/role` | 查询当前角色和星级。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/relation` | 查询邀请关系。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/tree` | 团队树页面。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/ancestors` | 查询上级链路。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/children` | 查询直属下级。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/descendants` | 分页查询下级成员。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/children-earnings` | 下级成员收益贡献。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/team-summary` | 团队汇总。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/network-overview` | 我的推广联盟页汇总。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/growth/users/{userId}/free-partner-upgrade` | Agent 免费升级 Partner 资格查询。 |
| 成长关系 | App 内 H5 | POST | `/api/v1/growth/users/{userId}/free-partner-upgrade` | 领取免费升级 Partner。 |
| 成长关系 | App 内 H5 / 独立 H5 | GET | `/api/v1/growth/invites/{referralCode}/preview` | 邀请码预览、升级优惠和推荐奖励提示。 |
| 成长关系 | App 内 H5 | POST | `/api/v1/rebate-fund/claim` | 输入团长邀请码领取返佣基金。 |
| 成长关系 | App 内 H5 | GET | `/api/v1/rebate-fund/users/{userId}` | 查询返佣基金状态。 |
| 课程升级 | App 内 H5 | GET | `/api/v1/course-plans` | 查询升级课程/套餐价目。 |
| 课程升级 | App 内 H5 | POST | `/api/v1/course-orders` | 创建课程/升级订单。 |
| 课程升级 | App 内 H5 | GET | `/api/v1/course-orders/{id}` | 查询单个课程订单。 |
| 课程升级 | App 内 H5 | GET | `/api/v1/course-orders` | 查询用户课程订单列表。 |
| 支付 | App 内 H5 | POST | `/api/v1/payments/create` | 钱包充值、课程订单等通用支付单创建。 |
| 支付 | App 内 H5 | GET | `/api/v1/payments/{id}` | 查询支付单状态。 |
| 支付 | 测试调试 | POST | `/api/v1/payments/{id}/mock-paid` | 测试环境模拟支付成功。 |
| 优惠券 | App 内 H5 | GET | `/api/v1/coupons` | 用户券包列表。 |
| 优惠券 | App 内 H5 | GET | `/api/v1/coupons/{id}` | 单张券详情。 |
| 优惠券 | App 内 H5 | POST | `/api/v1/coupons/{id}/claim` | 用户领取可领取券。 |
| 优惠券 | App 内 H5 | POST | `/api/v1/coupons/preview` | 订单、升级套餐等金额优惠预览。 |
| 活动运营 | App 内 H5 | GET | `/api/v1/activity-campaigns/cards` | 首页 Banner、商品详情活动卡片、活动弹窗数据。 |
| 活动运营 | App 内 H5 | GET | `/api/v1/campaigns/placements` | 首页 Banner、中心弹窗、悬浮入口等运营展示位。 |
| 活动运营 | App 内 H5 | GET | `/api/v1/activity-campaigns/rewards` | 活动奖励记录。 |
| TPB 奖励 | App 内 H5 | GET | `/api/v1/tpb-rewards` | TPB 奖励记录。 |
| 返现申诉 | App 内 H5 | POST | `/api/v1/cashback-appeals/attachments` | 上传返现问题申诉截图。 |
| 返现申诉 | App 内 H5 | POST | `/api/v1/cashback-appeals` | 提交返现问题申诉。 |
| 系统配置 | App / App 内 H5 / 独立 H5 | GET | `/api/v1/countries` | 查询支持国家列表。 |
| 系统配置 | App / App 内 H5 / 独立 H5 | GET | `/api/v1/app/runtime-config` | 查询运行时配置和功能开关。 |
| 系统配置 | App | GET | `/api/v1/app/h5-package/latest` | 查询当前环境最新 H5 包信息。 |
| 系统配置 | App | POST | `/api/v1/app/h5-package/report` | App 上报 H5 包下载、应用或失败结果。 |
| 日志推送 | App | GET | `/api/v1/app-logs/upload-token` | 获取 App 日志或附件上传凭证。 |
| 日志推送 | App | GET | `/api/v1/app-logs/sls-token` | 获取 SLS 日志上传临时凭证。 |
| 日志推送 | App | POST | `/api/v1/app-logs/feedback` | 提交 App 日志反馈。 |
| 日志推送 | App | POST | `/api/v1/push/devices/register` | 注册 App 推送设备。 |
| 日志推送 | App | POST | `/api/v1/push/devices/disable` | 禁用 App 推送设备。 |
| 日志推送 | App | GET | `/api/v1/push/devices` | 查询用户已注册推送设备。 |
| 日志推送 | 管理后台 / 系统任务 | POST | `/api/v1/push/notifications/users` | 给指定用户创建推送任务。 |
| 日志推送 | 管理后台 / 系统任务 | GET | `/api/v1/push/tasks/{taskId}` | 查询推送任务状态。 |
| 三方集成 | 管理后台 | GET | `/api/v1/integrations/tiktok/auth-url` | TikTok 平台账号授权入口。 |
| 三方集成 | 三方回调 | GET | `/api/v1/integrations/tiktok/callback` | TikTok 平台账号授权回调。 |
| 三方集成 | 管理后台 / 系统任务 | POST | `/api/v1/integrations/tiktok/accounts/{platformAccountId}/refresh` | 刷新 TikTok 平台账号 token。 |

### 11.1 管理后台配置接口清单

| 业务域 | 调用方 | Method | Path | 使用场景 |
| --- | --- | --- | --- | --- |
| 活动运营位 | 管理后台 | GET | `/api/v1/admin/campaign-placements` | 分页查询首页 Banner、弹窗、悬浮入口等活动坑位配置。 |
| 活动运营位 | 管理后台 | GET | `/api/v1/admin/campaign-placements/{id}` | 查询单个活动坑位配置详情。 |
| 活动运营位 | 管理后台 | POST | `/api/v1/admin/campaign-placements` | 创建活动坑位配置。 |
| 活动运营位 | 管理后台 | PUT | `/api/v1/admin/campaign-placements/{id}` | 更新活动坑位配置。 |
| 活动运营位 | 管理后台 | POST | `/api/v1/admin/campaign-placements/{id}/enable` | 启用活动坑位配置。 |
| 活动运营位 | 管理后台 | POST | `/api/v1/admin/campaign-placements/{id}/disable` | 停用活动坑位配置。 |
| 活动运营位 | 管理后台 | DELETE | `/api/v1/admin/campaign-placements/{id}` | 删除活动坑位配置。 |
| 活动运营位 | 管理后台 | GET | `/api/v1/admin/campaign-placements/options` | 查询后台下拉枚举。 |
| 活动运营位 | 管理后台 | POST | `/api/v1/admin/campaign-placements/{id}/preview` | 预览指定用户是否命中活动坑位。 |
| 奖励规则兼容接口 | 管理后台 | GET | `/api/v1/admin/rewards/rules` | 查询旧表 `reward_rule_config` 中的奖励规则。 |
| 奖励规则兼容接口 | 管理后台 | POST | `/api/v1/admin/rewards/rules` | 写入旧表奖励规则；新规则版本优先使用 `/api/v1/admin/config/rule-versions`。 |
| 奖励规则兼容接口 | 系统任务 | POST | `/api/v1/rewards/commissions/release-due` | 释放到期佣金。 |
| 团队佣金月结 | 系统任务 | POST | `/api/v1/rewards/team-commissions/settle` | 按月结任务制为指定 Partner 结算团队佣金。 |
| 规则版本配置 | 管理后台 | GET | `/api/v1/admin/config/rule-versions` | 分页查询佣金、提现、券、活动等业务规则版本。 |
| 规则版本配置 | 管理后台 | GET | `/api/v1/admin/config/rule-versions/{id}` | 查询单个业务规则版本。 |
| 规则版本配置 | 管理后台 | POST | `/api/v1/admin/config/rule-versions` | 创建业务规则版本草稿。 |
| 规则版本配置 | 管理后台 | PUT | `/api/v1/admin/config/rule-versions/{id}` | 更新业务规则版本草稿。 |
| 规则版本配置 | 管理后台 | POST | `/api/v1/admin/config/rule-versions/{id}/publish` | 发布业务规则版本，校验生效时间不重叠。 |
| 规则版本配置 | 管理后台 | POST | `/api/v1/admin/config/rule-versions/{id}/disable` | 停用业务规则版本。 |
| 运行开关配置 | 管理后台 | GET | `/api/v1/admin/config/runtime-features` | 分页查询 App/H5 运行开关。 |
| 运行开关配置 | 管理后台 | GET | `/api/v1/admin/config/runtime-features/{id}` | 查询单个运行开关配置。 |
| 运行开关配置 | 管理后台 | POST | `/api/v1/admin/config/runtime-features` | 创建运行开关配置。 |
| 运行开关配置 | 管理后台 | PUT | `/api/v1/admin/config/runtime-features/{id}` | 更新运行开关配置。 |
| 运行开关配置 | 管理后台 | DELETE | `/api/v1/admin/config/runtime-features/{id}` | 删除运行开关配置。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/overview` | 查询后台概览指标。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/users` | 查询后台用户列表。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/orders` | 查询后台订单列表。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/commissions` | 查询后台佣金列表。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/payments` | 查询后台支付列表。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/withdraws` | 查询后台提现列表。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/whatsapp/messages` | 查询 WhatsApp 消息列表。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/integrations` | 查询三方集成状态。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/risk-events` | 查询风控事件。 |
| 后台总览 | 管理后台 | GET | `/api/v1/admin/audit-logs` | 查询审计日志。 |
| 热门品牌配置 | 管理后台 | GET | `/api/v1/admin/popular-brands` | 查询热门品牌配置。 |
| 热门品牌配置 | 管理后台 | POST | `/api/v1/admin/popular-brands` | 创建或更新热门品牌配置。 |
| 热门品牌配置 | 管理后台 | POST | `/api/v1/admin/popular-brands/{id}/enabled` | 启用或停用热门品牌。 |
| 后台优惠券 | 管理后台 | GET | `/api/v1/admin/coupons` | 查询后台优惠券列表。 |
| 后台优惠券 | 管理后台 | POST | `/api/v1/admin/coupons/issue` | 后台发券。 |
| 后台优惠券 | 管理后台 | POST | `/api/v1/admin/coupons/{id}/cancel` | 后台取消优惠券。 |
| 后台优惠券 | 管理后台 / 系统任务 | POST | `/api/v1/admin/coupons/expire` | 过期已到期优惠券。 |
| H5 包管理 | 管理后台 | GET | `/api/v1/admin/h5-packages` | 查询 H5 包版本列表。 |
| H5 包管理 | 管理后台 | POST | `/api/v1/admin/h5-packages` | 创建 H5 包版本。 |
| H5 包管理 | 管理后台 | POST | `/api/v1/admin/h5-packages/{id}/publish` | 发布 H5 包版本。 |
| H5 包管理 | 管理后台 | POST | `/api/v1/admin/h5-packages/{id}/disable` | 停用 H5 包版本。 |
| H5 包管理 | 管理后台 | POST | `/api/v1/admin/h5-packages/{id}/rollback` | 回滚 H5 包版本。 |
| 新人返现基金配置 | 管理后台 | GET | `/api/v1/admin/rebate-fund-config` | 查询新人返现基金配置。 |
| 新人返现基金配置 | 管理后台 | POST | `/api/v1/admin/rebate-fund-config` | 保存新人返现基金配置。 |
| 运营监控 | 管理后台 | GET | `/api/v1/admin/ops/monitor-snapshot` | 查询运营监控快照。 |
| 运营监控 | 管理后台 / 系统任务 | POST | `/api/v1/admin/ops/monitor-check` | 执行运营监控检查。 |
| 推送任务 | 管理后台 | GET | `/api/v1/admin/push/tasks` | 查询推送任务列表。 |
| 推送任务 | 管理后台 | GET | `/api/v1/admin/push/tasks/{taskId}` | 查询推送任务详情。 |
| 推送任务 | 管理后台 / 系统任务 | POST | `/api/v1/admin/push/dispatch-due` | 派发到期推送任务。 |
| 后台提现审批 | 管理后台 | POST | `/api/v1/admin/withdraws/{id}/approve` | 审批通过提现。 |
| 后台提现审批 | 管理后台 | POST | `/api/v1/admin/withdraws/{id}/reject` | 拒绝提现。 |
| 邀请券规则 | 管理后台 | GET | `/api/v1/admin/coupon-campaigns/invite/rules` | 查询邀请券规则。 |
| 邀请券规则 | 管理后台 | POST | `/api/v1/admin/coupon-campaigns/invite/rules` | 创建或更新邀请券规则。 |
| 邀请券规则 | 系统任务 / 测试调试 | POST | `/api/v1/coupon-campaigns/invite/trigger` | 手动触发邀请券发放。 |
| 星级规则 | App 内 H5 / 管理后台 | GET | `/api/v1/star-rules` | 查询星级规则。 |
| 星级规则 | 管理后台 | POST | `/api/v1/star-rules` | 创建或更新星级规则。 |
| 活动规则 | 管理后台 | POST | `/api/v1/activity-campaigns` | 创建或更新活动。 |
| 活动规则 | 管理后台 | POST | `/api/v1/activity-campaigns/rules` | 创建或更新活动规则。 |
| 提现兼容审批 | 测试调试 / 管理后台 | POST | `/api/v1/withdraw/{id}/approve` | 兼容审批通过提现，需 `X-ADMIN-TOKEN`。 |
| 提现兼容审批 | 测试调试 / 管理后台 | POST | `/api/v1/withdraw/{id}/reject` | 兼容拒绝提现，需 `X-ADMIN-TOKEN`。 |

### 11.2 代码路由补充清单

本节用于和服务端 Controller 做机械核对，列出第 11.1 表格中已归属但分列展示的后台、Webhook、App Link 和兼容接口。

```http
GET /.well-known/apple-app-site-association
GET /.well-known/assetlinks.json
GET /apple-app-site-association
GET /s/{shareCode}
GET /webhooks/whatsapp
POST /webhooks/whatsapp
POST /webhooks/xendit/invoices
POST /webhooks/xendit/disbursements
POST /webhooks/feishu/events
POST /webhooks/apple/sign-in

GET /api/v1/admin/overview
GET /api/v1/admin/users
GET /api/v1/admin/orders
GET /api/v1/admin/commissions
GET /api/v1/admin/payments
GET /api/v1/admin/withdraws
GET /api/v1/admin/whatsapp/messages
GET /api/v1/admin/integrations
GET /api/v1/admin/risk-events
GET /api/v1/admin/audit-logs

GET /api/v1/admin/config/rule-versions/{id}
GET /api/v1/admin/config/runtime-features/{id}
GET /api/v1/admin/coupons
POST /api/v1/admin/coupons/issue
POST /api/v1/admin/coupons/{id}/cancel
POST /api/v1/admin/coupons/expire
GET /api/v1/admin/h5-packages
POST /api/v1/admin/h5-packages
POST /api/v1/admin/h5-packages/{id}/publish
POST /api/v1/admin/h5-packages/{id}/disable
POST /api/v1/admin/h5-packages/{id}/rollback
GET /api/v1/admin/popular-brands
POST /api/v1/admin/popular-brands
POST /api/v1/admin/popular-brands/{id}/enabled
GET /api/v1/admin/rebate-fund-config
POST /api/v1/admin/rebate-fund-config
GET /api/v1/admin/ops/monitor-snapshot
POST /api/v1/admin/ops/monitor-check
GET /api/v1/admin/push/tasks
GET /api/v1/admin/push/tasks/{taskId}
POST /api/v1/admin/push/dispatch-due
POST /api/v1/admin/withdraws/{id}/approve
POST /api/v1/admin/withdraws/{id}/reject

GET /api/v1/admin/coupon-campaigns/invite/rules
POST /api/v1/admin/coupon-campaigns/invite/rules
POST /api/v1/coupon-campaigns/invite/trigger
GET /api/v1/star-rules
POST /api/v1/star-rules
POST /api/v1/activity-campaigns
POST /api/v1/activity-campaigns/rules
POST /api/v1/course-plans
POST /api/v1/withdraw/{id}/approve
POST /api/v1/withdraw/{id}/reject
```

## 12. 页面模块接口索引

本节按 App/H5 页面组织，便于前端接入时确认页面需要调用哪些接口。接口详情见第 13 节。

| 模块 | 页面/场景 | 接口 | 作用 |
| --- | --- | --- | --- |
| Home 首页 | 首页 Tab | `POST /api/v1/products/high-commission` | 查询高返佣商品池。 |
| Home 首页 | 首页 Tab | `GET /api/v1/popular-brands` | 查询热门品牌入口。 |
| Home 首页 | 首页 Tab | `GET /api/v1/activity-campaigns/cards` | 查询首页 Banner、活动卡片、新用户券入口。 |
| Home 首页 | 活动 Banner / 活动弹窗 / 悬浮入口 | `GET /api/v1/campaigns/placements` | 按 `HOME_BANNER`、`HOME_POPUP`、`HOME_FLOATING_ENTRY` 查询可展示活动配置。 |
| Home 首页 | 粘贴链接/剪切板识别 | `POST /api/v1/links/parse` | 轻量判断链接平台和商品 ID。 |
| Home 首页 | 粘贴链接/剪切板识别 | `POST /api/v1/products/resolve` | 解析第三方商品链接并返回 BeeX 商品展示数据。 |
| Home 首页 | BeeX 分享链接识别 | `GET /api/v1/affiliate-shares/{shareCode}` | 查询 BeeX 分享链接是否有效并获取商品快照。 |
| Product 商品模块 | 商品搜索/商品池 | `POST /api/v1/products/high-commission` | 按平台、关键字、游标分页查询商品。 |
| Product 商品模块 | 商品详情 | `POST /api/v1/products/resolve` | 查询商品详情基础信息。 |
| Product 商品模块 | 商品详情 | `POST /api/v1/coupons/preview` | 预览优惠券对预计返利/价格的影响。 |
| Product 商品模块 | 商品详情更多推荐 | `POST /api/v1/products/recommendations` | 查询同店铺、同类目或详情页推荐商品。 |
| Product 商品模块 | 去 TikTok/Shopee 下单 | `POST /api/v1/affiliate-links/generate` | 生成购买链接、clickId、trackingTag。 |
| Product 商品模块 | 分享商品 | `POST /api/v1/affiliate-links/generate` | `linkMode=SHARE` 时生成 BeeX 分享链接。 |
| Share / Invite | 商品分享承接页 | `GET /api/v1/affiliate-shares/{shareCode}` | 查询分享链接详情。 |
| Share / Invite | 商品分享承接页 | `POST /api/v1/affiliate-shares/{shareCode}/clicks` | 记录打开分享链接，并在满足规则时绑定邀请关系。 |
| Share / Invite | 邀请码承接页 | `GET /api/v1/growth/invites/{referralCode}/preview` | 校验邀请码、计算课程邀请优惠和推荐奖励。 |
| Earnings / Orders | 收益 Tab | `GET /api/v1/earnings/{userId}/summary` | 查询钱包和订单/佣金汇总。 |
| Earnings / Orders | 我的订单 | `GET /api/v1/earnings/{userId}/orders` | 查询已生成订单列表。 |
| Earnings / Orders | 收入明细 | `GET /api/v1/earnings/{userId}/commissions` | 查询佣金明细。 |
| Earnings / Orders | 订单追踪 | `GET /api/v1/order-tracking/users/{userId}` | 查询尚未确认或已确认的转链订单追踪记录。 |
| Earnings / Orders | 返现问题申诉 | `POST /api/v1/cashback-appeals/attachments` | 上传申诉截图。 |
| Earnings / Orders | 返现问题申诉 | `POST /api/v1/cashback-appeals` | 提交返现问题申诉。 |
| Wallet / Withdraw / KYC | 钱包总览 | `GET /api/v1/wallets/{userId}` | 查询待结算、可提现、冻结、累计收益。 |
| Wallet / Withdraw / KYC | 提现资料 | `GET /api/v1/withdraw/payout-profile` | 查询 KYC/提现账号资料。 |
| Wallet / Withdraw / KYC | 提现资料 | `POST /api/v1/withdraw/payout-profile` | 保存 KYC/提现账号资料。 |
| Wallet / Withdraw / KYC | 提现申请 | `POST /api/v1/withdraw/apply` | 发起提现申请。 |
| Wallet / Withdraw / KYC | 提现记录 | `GET /api/v1/withdraw/records` | 查询提现状态列表。 |
| Team 团队模块 | 我的推广联盟入口 | `GET /api/v1/growth/users/{userId}/team-summary` | 查询团队人数、角色统计。 |
| Team 团队模块 | 我的推广联盟页 | `GET /api/v1/growth/users/{userId}/network-overview` | 查询联盟汇总、成员分页、角色/星级筛选。 |
| Team 团队模块 | 我的推广联盟页 | `GET /api/v1/growth/users/{userId}/descendants` | 查询下级成员列表。 |
| Team 团队模块 | 我的推广联盟页 | `GET /api/v1/growth/users/{userId}/children-earnings` | 查询下级成员贡献收益。 |
| Role Upgrade | 会员体系页 | `GET /api/v1/growth/users/{userId}/role` | 查询当前角色和星级。 |
| Role Upgrade | 升级弹窗 | `GET /api/v1/course-plans` | 查询可购买课程/升级套餐。 |
| Role Upgrade | 升级弹窗 | `GET /api/v1/growth/invites/{referralCode}/preview` | 校验邀请码优惠。 |
| Role Upgrade | 升级弹窗 | `POST /api/v1/coupons/preview` | 预览升级优惠券。 |
| Role Upgrade | 创建升级订单 | `POST /api/v1/course-orders` | 创建课程订单和支付单。 |
| Role Upgrade | 支付结果页 | `GET /api/v1/course-orders/{id}` | 查询课程订单结果。 |
| Role Upgrade | 支付结果页 | `GET /api/v1/payments/{id}` | 查询支付状态。 |
| Role Upgrade | 本地测试支付 | `POST /api/v1/payments/{id}/mock-paid` | 测试环境模拟支付成功。 |
| Coupon / Campaign | 我的优惠券 | `GET /api/v1/coupons` | 查询用户券包。 |
| Coupon / Campaign | 优惠券详情/历史 | `GET /api/v1/coupons/{id}` | 查询单张券详情。 |
| Coupon / Campaign | 领取优惠券 | `POST /api/v1/coupons/{id}/claim` | 手动领取可领取券。 |
| Coupon / Campaign | 商品详情活动卡 | `GET /api/v1/activity-campaigns/cards` | 查询活动卡片。 |
| Coupon / Campaign | 活动展示位 | `GET /api/v1/campaigns/placements` | 查询 Banner、弹窗、悬浮入口等活动运营位配置。 |
| Coupon / Campaign | 活动奖励记录 | `GET /api/v1/activity-campaigns/rewards` | 查询活动奖励记录。 |
| Me 我的模块 | 我的 Tab | `GET /api/v1/users/{userId}/profile` | 查询用户资料、邀请码、角色摘要。 |
| Me 我的模块 | 我的 Tab | `GET /api/v1/coupons` | 查询优惠券数量。 |
| Me 我的模块 | 我的 Tab | `GET /api/v1/growth/users/{userId}/team-summary` | 查询联盟人数。 |
| Me 我的模块 | 我的 Tab | `GET /api/v1/earnings/{userId}/orders` | 查询最近订单图片。 |
| Me 我的模块 | 编辑资料 | `PUT /api/v1/users/{userId}/profile` | 更新昵称、头像 URL。 |
| Me 我的模块 | 上传头像 | `POST /api/v1/users/{userId}/avatar` | 上传头像文件。 |
| Auth Bridge | 登录方式页 | `GET /api/v1/auth/options` | 查询当前环境启用的登录方式。 |
| Auth Bridge | WhatsApp 登录 | `POST /api/v1/auth/whatsapp/login-intents` | 创建 WhatsApp 登录意图。 |
| Auth Bridge | WhatsApp 登录 | `GET /api/v1/auth/whatsapp/login-intents/{id}` | 轮询登录状态。 |
| Auth Bridge | WhatsApp 登录 | `POST /api/v1/auth/whatsapp/login-intents/{id}/consume` | 消费已验证登录意图并换 token。 |
| Auth Bridge | 手机 OTP 登录 | `POST /api/v1/auth/phone/otp-intents` | 创建短信/WhatsApp OTP 意图。 |
| Auth Bridge | 手机 OTP 登录 | `POST /api/v1/auth/phone/otp-intents/{otpIntentId}/verify` | 校验 OTP 并登录。 |
| Auth Bridge | TikTok 登录 | `GET /api/v1/auth/tiktok/auth-url` | 创建 TikTok OAuth 授权 URL。 |
| Auth Bridge | TikTok 登录 | `POST /api/v1/auth/tiktok/callback` | 用 code/state 完成登录。 |
| Auth Bridge | Google 登录 | `POST /api/v1/auth/google/id-token` | 用 Google ID Token 完成登录。 |
| Auth Bridge | Apple 登录 | `POST /api/v1/auth/apple/native` | iOS 原生 Apple 登录。 |

## 13. H5/App 接口详情字典

### 13.1 文档字段约定

| 字段 | 说明 |
| --- | --- |
| 参数位置 | `Path` 为路径参数，`Query` 为 URL 查询参数，`Body` 为 JSON 请求体，`FormData` 为表单字段。 |
| 必填 | `是` 表示客户端必须传；`否` 表示不传时服务端使用默认值或忽略。 |
| 金额字段 | 所有 `*Minor` 都是最小货币单位，例如 IDR 场景 `500000` 表示 Rp5.000。 |
| 时间字段 | 默认使用 ISO 8601 字符串，例如 `2026-06-01T18:30:00`。 |
| 返回结构 | 外层统一为 `{ success: boolean, message: string, data: T }`，下方只描述 `data`。 |
| 调用方 | 说明接口主要由 `App`、`App 内 H5`、`独立 H5`、`管理后台`、`三方回调` 或 `测试调试` 调用。 |
| 业务域 | 说明接口归属的业务模块，例如登录认证、商品与转链、成长关系、钱包提现、活动运营、系统配置。 |
| 使用场景 | 说明接口服务的具体页面或链路；同一接口被多端复用时，以第 11 节归属总览为准。 |

### 13.2 登录认证接口

#### GET /api/v1/auth/options

接口作用：查询当前国家、客户端类型可用的登录方式。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Query | `clientType` | string | 否 | 客户端类型，默认 `h5`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `countryCode` | string | 是 | 国家码。 |
| `clientType` | string | 是 | 客户端类型。 |
| `methods[].key` | string | 是 | 登录方式：`PHONE_ID`、`WHATSAPP`、`TIKTOK`、`GOOGLE`、`APPLE`。 |
| `methods[].enabled` | boolean | 是 | 是否启用。 |
| `methods[].nativePreferred` | boolean | 否 | 是否优先走原生登录。 |
| `methods[].clientId` | string | 否 | 三方登录 clientId。 |
| `methods[].reason` | string | 否 | 不可用原因。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/auth/options?countryCode=ID&clientType=h5'
```

#### POST /api/v1/auth/whatsapp/login-intents

接口作用：创建 WhatsApp 登录意图，返回 WhatsApp 跳转链接和登录码。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `clientType` | string | 是 | 客户端类型。 |
| Body | `deviceId` | string | 是 | 设备 ID。 |
| Body | `returnUrl` | string | 是 | 登录完成后的 H5 回跳地址。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `loginIntentId` | string | 是 | 登录意图 ID。 |
| `loginCode` | string | 是 | 用户发给 WhatsApp Bot 的登录码。 |
| `expiresIn` | number | 是 | 有效期秒数。 |
| `whatsappUrl` | string | 是 | WhatsApp 跳转链接。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/whatsapp/login-intents' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","clientType":"h5","deviceId":"device_xxx","returnUrl":"https://www.beexofficial.com/auth?source=h5_whatsapp_login"}'
```

#### GET /api/v1/auth/whatsapp/login-intents/{id}

接口作用：轮询 WhatsApp 登录意图状态，可选消费登录结果。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 登录意图 ID。 |
| Query | `consume` | boolean | 否 | 是否在查询时消费登录结果，默认 `false`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `loginIntentId` | string | 是 | 登录意图 ID。 |
| `status` | string | 是 | `CREATED`、`VERIFIED`、`CONSUMED`、`EXPIRED`。 |
| `userId` | string | 否 | 验证成功后的用户 ID。 |
| `countryCode` | string | 否 | 国家码。 |
| `displayName` | string | 否 | 用户显示名。 |
| `whatsappNumber` | string | 否 | WhatsApp 号码。 |
| `referralCode` | string | 否 | 用户邀请码。 |
| `accessToken` | string | 否 | 消费后返回的访问 token。 |
| `refreshToken` | string | 否 | 消费后返回的刷新 token。 |
| `expiresIn` | number | 否 | token 有效期秒数。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/auth/whatsapp/login-intents/lgi_xxx?consume=false'
```

#### POST /api/v1/auth/whatsapp/login-intents/{id}/consume

接口作用：消费已验证的 WhatsApp 登录意图并换取 token。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 登录意图 ID。 |

返回参数：同 `GET /api/v1/auth/whatsapp/login-intents/{id}`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/whatsapp/login-intents/lgi_xxx/consume' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

#### POST /api/v1/auth/phone/otp-intents

接口作用：创建手机 OTP 登录意图。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `phoneNumber` | string | 是 | 手机号。 |
| Body | `deviceId` | string | 是 | 设备 ID。 |
| Body | `clientType` | string | 是 | 客户端类型。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `otpIntentId` | string | 是 | OTP 意图 ID。 |
| `expiresIn` | number | 是 | 有效期秒数。 |
| `maskedPhone` | string | 是 | 脱敏手机号。 |
| `devCode` | string | 否 | 测试环境调试验证码。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/phone/otp-intents' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","phoneNumber":"08123456789","deviceId":"device_xxx","clientType":"h5"}'
```

#### POST /api/v1/auth/phone/otp-intents/{otpIntentId}/verify

接口作用：校验 OTP 并完成登录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `otpIntentId` | string | 是 | OTP 意图 ID。 |
| Body | `code` | string | 是 | 用户输入的验证码。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | string | 是 | 用户 ID。 |
| `countryCode` | string | 是 | 国家码。 |
| `newUser` | boolean | 否 | 是否新用户。 |
| `provider` | string | 是 | 登录提供方。 |
| `providerUserId` | string | 否 | 三方用户 ID。 |
| `displayName` | string | 否 | 显示名。 |
| `avatarUrl` | string | 否 | 头像。 |
| `phoneNumber` | string | 否 | 手机号。 |
| `referralCode` | string | 否 | 用户邀请码。 |
| `accessToken` | string | 是 | 访问 token。 |
| `refreshToken` | string | 是 | 刷新 token。 |
| `expiresIn` | number | 是 | token 有效期秒数。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/phone/otp-intents/otp_xxx/verify' \
  -H 'Content-Type: application/json' \
  -d '{"code":"123456"}'
```

#### GET /api/v1/auth/tiktok/auth-url

接口作用：创建 TikTok 用户登录 OAuth 授权链接。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `deviceId` | string | 是 | 设备 ID。 |
| Query | `returnUrl` | string | 否 | 登录完成后的回跳地址。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `authorizationUrl` | string | 是 | TikTok OAuth 授权 URL。 |
| `state` | string | 是 | OAuth state。 |
| `redirectUri` | string | 是 | OAuth 回调地址。 |
| `expiresIn` | number | 是 | 有效期秒数。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/auth/tiktok/auth-url?countryCode=ID&deviceId=device_xxx'
```

#### POST /api/v1/auth/tiktok/callback

接口作用：用 TikTok OAuth `code` 和 `state` 完成用户登录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `code` | string | 是 | TikTok OAuth code。 |
| Body | `state` | string | 是 | 创建授权 URL 时返回的 state。 |

返回参数：同 `ProviderLoginResponse`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/tiktok/callback' \
  -H 'Content-Type: application/json' \
  -d '{"code":"oauth_code","state":"state_xxx"}'
```

#### POST /api/v1/auth/google/id-token

接口作用：用 Google ID Token 完成登录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `deviceId` | string | 是 | 设备 ID。 |
| Body | `idToken` | string | 是 | Google ID Token。 |
| Body | `nonce` | string | 否 | Google 登录 nonce。 |

返回参数：同 `ProviderLoginResponse`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/google/id-token' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","deviceId":"device_xxx","idToken":"google_id_token"}'
```

#### POST /api/v1/auth/apple/native

接口作用：iOS 原生 Apple 登录，用原生侧拿到的 identityToken / authorizationCode 完成登录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `deviceId` | string | 是 | 设备 ID。 |
| Body | `identityToken` | string | 是 | Apple identity token。 |
| Body | `authorizationCode` | string | 否 | Apple authorization code。 |
| Body | `fullName` | string | 否 | 首次授权时 Apple 返回的姓名。 |
| Body | `email` | string | 否 | 首次授权时 Apple 返回的邮箱。 |

返回参数：同 `ProviderLoginResponse`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/apple/native' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","deviceId":"device_xxx","identityToken":"apple_identity_token"}'
```

#### POST /api/v1/auth/apple/callback

接口作用：Apple Web 登录 callback 承接，通常由 Apple 表单回调调用。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body/Form | `code` | string | 是 | Apple authorization code。 |
| Body/Form | `id_token` | string | 否 | Apple identity token。 |
| Body/Form | `state` | string | 否 | 登录 state。 |

返回参数：同 `ProviderLoginResponse` 或回调跳转响应，取决于调用方式。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/apple/callback' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'code=apple_code' \
  --data-urlencode 'state=state_xxx'
```

#### GET /api/v1/auth/apple/callback

接口作用：Apple Web 登录 GET callback 兼容入口。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `code` | string | 是 | Apple authorization code。 |
| Query | `state` | string | 否 | 登录 state。 |

返回参数：同 Apple Web callback 处理结果。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/auth/apple/callback?code=apple_code&state=state_xxx'
```

#### POST /api/v1/auth/apple/android-callback

接口作用：Android Sign in with Apple 的 Web callback 承接。

请求参数：同 `POST /api/v1/auth/apple/callback`。

返回参数：同 `ProviderLoginResponse` 或回调跳转响应。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/auth/apple/android-callback' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'code=apple_code' \
  --data-urlencode 'state=state_xxx'
```

### 13.3 商品、转链与分享接口

#### POST /api/v1/products/high-commission

接口作用：查询首页或商品池高返佣商品，支持关键字、平台和游标分页。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `platform` | string | 否 | `TIKTOK` 或 `SHOPEE`；不传表示混合。 |
| Body | `keyword` | string | 否 | 搜索关键字。 |
| Body | `limit` | number | 是 | 返回数量。 |
| Body | `cursor` | string | 否 | 下一页游标。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `products` | ProductItem[] | 是 | 商品列表。 |
| `products[].id` | string | 是 | BeeX 商品 ID。 |
| `products[].platformProductId` | string | 否 | 三方平台商品 ID。 |
| `products[].name` | string | 是 | 商品名。 |
| `products[].brand` | string | 是 | 品牌名。 |
| `products[].platform` | string | 是 | 平台。 |
| `products[].imageUrl` | string | 否 | 商品图。 |
| `products[].cashbackRate` | number | 是 | 返现比例。 |
| `products[].cashbackMinor` | number | 否 | 预计返现金额。 |
| `products[].priceMinor` | number | 是 | 商品价格。 |
| `products[].currency` | string | 否 | 币种。 |
| `products[].productUrl` | string | 否 | 商品原始链接。 |
| `pageInfo.hasNext` | boolean | 否 | 是否还有下一页。 |
| `pageInfo.nextCursor` | string | 否 | 下一页游标。 |
| `warnings` | string[] | 是 | 查询警告。 |

调用示例：

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

#### POST /api/v1/products/resolve

接口作用：解析第三方商品链接，返回商品详情页所需的商品快照。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `productUrl` | string | 是 | TikTok/Tokopedia/Shopee 商品链接。 |
| Body | `platformProductId` | string | 否 | 已知平台商品 ID，可帮助服务端直接查询。 |

返回参数：同 `ProductItem`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/products/resolve' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","productUrl":"https://shop-id.tokopedia.com/view/product/1729618560920816365"}'
```

#### POST /api/v1/products/recommendations

接口作用：查询商品详情页更多推荐，支持按店铺或类目推荐。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Body | `scene` | string | 否 | 推荐场景：`SHOP` 或 `CATEGORY`，默认 `CATEGORY`。 |
| Body | `platform` | string | 否 | 平台。 |
| Body | `keyword` | string | 否 | 搜索关键词。 |
| Body | `shopId` | string | 否 | 店铺 ID，`scene=SHOP` 时优先使用。 |
| Body | `shopName` | string | 否 | 店铺名称。 |
| Body | `categoryId` | string | 否 | 类目 ID，`scene=CATEGORY` 时优先使用。 |
| Body | `categoryName` | string | 否 | 类目名称。 |
| Body | `excludeProductId` | string | 否 | 需要排除的 BeeX 商品 ID。 |
| Body | `excludePlatformProductId` | string | 否 | 需要排除的平台商品 ID。 |
| Body | `pageSize` | number | 否 | 返回数量。 |
| Body | `cursor` | string | 否 | 分页游标。 |

返回参数：`products` 同 `ProductItem[]`，`pageInfo` 为分页信息，`warnings` 为警告列表。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/products/recommendations' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","platform":"TIKTOK","scene":"CATEGORY","categoryName":"Vacuum Cleaner","excludePlatformProductId":"1729618560920816365","pageSize":20}'
```

#### POST /api/v1/links/parse

接口作用：轻量解析链接来源和商品 ID，用于首页粘贴链接前置判断。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `url` | string | 是 | 待解析链接。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `platform` | string | 是 | `TIKTOK`、`SHOPEE`、`LAZADA`、`OTHER`。 |
| `productUrl` | string | 是 | 规范化后的商品 URL。 |
| `platformProductId` | string | 否 | 平台商品 ID。 |
| `rawUrl` | string | 否 | 原始 URL。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/links/parse' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://shop-id.tokopedia.com/view/product/1729618560920816365"}'
```

#### POST /api/v1/shopee/product-offers

接口作用：查询 Shopee Product Offer，用于 Shopee 商品调试或商品 Offer 查询。

请求参数：请求体透传 Shopee Product Offer V2 查询参数，字段以后端 Shopee 集成模型为准。

返回参数：Shopee 原始 Product Offer V2 JSON。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/shopee/product-offers' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","itemIds":["123456"]}'
```

#### GET /api/v1/popular-brands

接口作用：查询首页热门品牌入口。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `limit` | number | 否 | 返回数量，默认由服务端决定。 |
| Query | `enabledOnly` | boolean | 否 | 是否只返回启用品牌。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].id` | string | 是 | 品牌配置 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].iconUrl` | string | 否 | 图标。 |
| `[].searchKeyword` | string | 是 | 点击后用于搜索的关键字。 |
| `[].brandName` | string | 是 | 品牌名。 |
| `[].description` | string | 否 | 描述。 |
| `[].cashbackBps` | number | 是 | 返现基点。 |
| `[].sortOrder` | number | 是 | 排序值。 |
| `[].enabled` | boolean | 是 | 是否启用。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/popular-brands?countryCode=ID&limit=12&enabledOnly=true'
```

#### POST /api/v1/affiliate-links/generate

接口作用：生成三方平台购买链接；`linkMode=SHARE` 时同时生成 BeeX 商品分享链接。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 生成链接的用户。 |
| Body | `productUrl` | string | 是 | 商品原始链接。 |
| Body | `platformProductId` | string | 否 | 平台商品 ID。 |
| Body | `campaignId` | string | 否 | 活动 ID。 |
| Body | `referralCode` | string | 否 | 邀请码。 |
| Body | `channel` | string | 否 | 渠道，例如 `h5`。 |
| Body | `deviceId` | string | 否 | 设备 ID。 |
| Body | `linkMode` | string | 否 | `DIRECT` 或 `SHARE`。 |
| Body | `productName` | string | 否 | 商品名快照。 |
| Body | `imageUrl` | string | 否 | 商品图快照。 |
| Body | `priceMinor` | number | 否 | 商品价格快照。 |
| Body | `cashbackMinor` | number | 否 | 预计返现快照。 |
| Body | `currency` | string | 否 | 币种。 |
| Body | `couponId` | string | 否 | 用户选择的优惠券 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `clickId` | string | 是 | 转链点击 ID，也是订单归因关键 ID。 |
| `platform` | string | 是 | 平台。 |
| `originalUrl` | string | 是 | 原始商品 URL。 |
| `affiliateUrl` | string | 是 | 佣金链接。 |
| `purchaseUrl` | string | 否 | 用于跳转下单的链接。 |
| `shareUrl` | string | 否 | BeeX 分享链接。 |
| `shareCode` | string | 否 | 分享码。 |
| `linkMode` | string | 否 | 链接模式。 |
| `trackingTag` | string | 是 | 三方平台追踪 tag。 |
| `note` | string | 是 | 服务端说明。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/affiliate-links/generate' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","productUrl":"https://shop-id.tokopedia.com/view/product/1729618560920816365","channel":"h5","deviceId":"device_xxx","linkMode":"SHARE"}'
```

#### GET /api/v1/affiliate-shares/{shareCode}

接口作用：查询 BeeX 商品分享链接详情。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `shareCode` | string | 是 | 分享码，例如 `/s/{shareCode}` 中的部分。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `shareCode` | string | 是 | 分享码。 |
| `shareUrl` | string | 是 | BeeX 分享链接。 |
| `purchaseUrl` | string | 是 | 下单跳转链接。 |
| `platform` | string | 是 | 平台。 |
| `productUrl` | string | 是 | 商品原始链接。 |
| `productName` | string | 否 | 商品名快照。 |
| `imageUrl` | string | 否 | 商品图快照。 |
| `priceMinor` | number | 否 | 商品价格快照。 |
| `cashbackMinor` | number | 否 | 预计返现快照。 |
| `currency` | string | 否 | 币种。 |
| `shareUserId` | string | 否 | 分享人用户 ID。 |
| `referralCode` | string | 否 | 分享人邀请码。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/affiliate-shares/BXSX9R38RREN'
```

#### POST /api/v1/affiliate-shares/{shareCode}/clicks

接口作用：记录分享链接打开事件，并在满足规则时建立邀请关系。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `shareCode` | string | 是 | 分享码。 |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `clickUserId` | string | 否 | 打开链接的登录用户；游客可不传。 |
| Body | `channel` | string | 否 | 渠道，例如 `h5`。 |
| Body | `source` | string | 否 | 来源，例如 `share_landing`。 |
| Body | `deviceId` | string | 是 | 设备 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `bound` | boolean | 是 | 是否成功绑定关系。 |
| `reason` | string | 是 | `BOUND_SUCCESS`、`ALREADY_BOUND_TO_SAME_INVITER`、`ALREADY_BOUND_TO_OTHER_INVITER`、`SELF_INVITE_NOT_ALLOWED`、`GUEST_CLICK_ONLY`。 |
| `shareUserId` | string | 否 | 分享人 ID。 |
| `clickUserId` | string | 否 | 点击人 ID。 |
| `parentUserId` | string | 否 | 点击人当前上级 ID。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/affiliate-shares/BXSX9R38RREN/clicks' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","clickUserId":"usr_xxx","channel":"h5","source":"share_landing","deviceId":"device_xxx"}'
```

### 13.4 收益、订单、钱包与提现接口

#### GET /api/v1/earnings/{userId}/summary

接口作用：查询收益页汇总，包括钱包、订单统计和佣金统计。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `wallet` | WalletModel/null | 是 | 钱包余额信息。 |
| `orderStats.totalOrders` | number | 是 | 总订单数。 |
| `orderStats.pendingOrders` | number | 是 | 待处理订单数。 |
| `orderStats.completedOrders` | number | 是 | 已完成订单数。 |
| `orderStats.cancelledOrders` | number | 是 | 已取消订单数。 |
| `orderStats.grossAmountMinor` | number | 是 | 订单总额。 |
| `orderStats.cashbackMinor` | number | 是 | 返现金额。 |
| `commissionStats.totalCommissionMinor` | number | 是 | 总佣金。 |
| `commissionStats.pendingCommissionMinor` | number | 是 | 待结算佣金。 |
| `commissionStats.availableCommissionMinor` | number | 是 | 可提现佣金。 |
| `commissionStats.frozenCommissionMinor` | number | 是 | 冻结佣金。 |
| `commissionStats.paidCommissionMinor` | number | 是 | 已提现佣金。 |
| `commissionStats.invalidCommissionMinor` | number | 是 | 无效佣金。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/earnings/usr_xxx/summary'
```

#### GET /api/v1/earnings/{userId}/orders

接口作用：查询我的订单列表，只返回用户侧可展示的订单和返现字段。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量，H5 默认 `20`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].id` | string | 是 | BeeX 订单 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].platform` | string | 是 | 平台。 |
| `[].platformOrderId` | string | 是 | 平台订单号。 |
| `[].clickId` | string | 否 | 关联转链 clickId。 |
| `[].userId` | string | 是 | 归属用户。 |
| `[].currency` | string | 是 | 币种。 |
| `[].grossAmountMinor` | number | 是 | 订单总额。 |
| `[].cashbackMinor` | number | 是 | 用户返现金额。 |
| `[].productName` | string | 否 | 商品名快照。 |
| `[].imageUrl` | string | 否 | 商品图快照。 |
| `[].productUrl` | string | 否 | 商品链接。 |
| `[].priceMinor` | number | 否 | 商品价格。 |
| `[].status` | string | 是 | 订单状态。 |
| `[].commissionStatus` | string | 否 | 佣金状态。 |
| `[].orderedAt` | string | 否 | 下单时间。 |
| `[].settledAt` | string | 否 | 结算时间。 |
| `[].releaseAt` | string | 否 | 可提现时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/earnings/usr_xxx/orders?limit=20'
```

#### GET /api/v1/earnings/{userId}/commissions

接口作用：查询佣金流水明细。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].id` | string | 是 | 佣金记录 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].orderId` | string | 是 | 关联订单 ID。 |
| `[].beneficiaryUserId` | string | 是 | 收益归属用户。 |
| `[].sourceUserId` | string | 否 | 收益来源用户。 |
| `[].role` | string | 是 | 佣金角色/类型。 |
| `[].relationDepth` | number | 是 | 关系深度。 |
| `[].commissionAmountMinor` | number | 是 | 佣金金额。 |
| `[].status` | string | 是 | 佣金状态。 |
| `[].releaseAt` | string | 否 | 可提现时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/earnings/usr_xxx/commissions?limit=50'
```

#### GET /api/v1/order-tracking/users/{userId}

接口作用：查询订单追踪列表。追踪记录来自转链 clickId，订单同步后会补充订单信息。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].clickId` | string | 是 | 转链点击 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].platform` | string | 是 | 平台。 |
| `[].userId` | string | 是 | 用户 ID。 |
| `[].productUrl` | string | 否 | 商品链接。 |
| `[].affiliateUrl` | string | 否 | 佣金链接。 |
| `[].trackingTag` | string | 否 | 追踪 tag。 |
| `[].clickedAt` | string | 否 | 转链时间。 |
| `[].orderId` | string | 否 | BeeX 订单 ID。 |
| `[].platformOrderId` | string | 否 | 平台订单号。 |
| `[].orderStatus` | string | 否 | 订单状态。 |
| `[].commissionStatus` | string | 否 | 佣金状态。 |
| `[].orderedAt` | string | 否 | 下单时间。 |
| `[].releaseAt` | string | 否 | 可提现时间。 |
| `[].currency` | string | 否 | 币种。 |
| `[].grossAmountMinor` | number | 否 | 订单总额。 |
| `[].cashbackMinor` | number | 否 | 用户返现。 |
| `[].productName` | string | 否 | 商品名快照。 |
| `[].imageUrl` | string | 否 | 商品图快照。 |
| `[].priceMinor` | number | 否 | 商品价格快照。 |
| `[].trackingStatus` | string | 否 | `TRACKING`、`SUCCESS`、`MISSING`。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/order-tracking/users/usr_xxx?limit=100'
```

#### GET /api/v1/wallets/{userId}

接口作用：查询钱包余额。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | string | 是 | 用户 ID。 |
| `countryCode` | string | 是 | 国家码。 |
| `currency` | string | 是 | 币种。 |
| `pendingBalanceMinor` | number | 是 | 待结算余额。 |
| `availableBalanceMinor` | number | 是 | 可提现余额。 |
| `frozenBalanceMinor` | number | 是 | 冻结余额。 |
| `riskHoldBalanceMinor` | number | 是 | 风控冻结余额。 |
| `totalEarnedMinor` | number | 是 | 累计收益。 |
| `totalWithdrawnMinor` | number | 是 | 累计提现。 |
| `updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/wallets/usr_xxx'
```

#### GET /api/v1/withdraw/payout-profile

接口作用：查询提现资料。真实返回为列表；未配置时返回空数组。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |

返回参数：`PayoutProfile[]`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/withdraw/payout-profile?userId=usr_xxx'
```

#### POST /api/v1/withdraw/payout-profile

接口作用：保存 KYC/提现收款资料。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `fullName` | string | 是 | 真实姓名。 |
| Body | `idType` | string | 是 | 证件类型。 |
| Body | `idNumber` | string | 是 | 证件号。 |
| Body | `payoutProvider` | string | 是 | 收款方式，例如 `BANK`。 |
| Body | `bankName` | string | 是 | 银行名。 |
| Body | `bankAccountNumber` | string | 是 | 银行账号。 |
| Body | `bankAccountHolderName` | string | 是 | 银行账户名。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 提现资料 ID。 |
| `status` | string | 是 | 审核状态。 |
| `rejectReason` | string | 否 | 驳回原因。 |
| 其他字段 | string | 是 | 与请求字段一致。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/withdraw/payout-profile' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","fullName":"User Name","idType":"ID_CARD","idNumber":"123456","payoutProvider":"BANK","bankName":"BCA","bankAccountNumber":"1234567890","bankAccountHolderName":"User Name"}'
```

#### POST /api/v1/withdraw/apply

接口作用：发起提现申请。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `amountMinor` | number | 是 | 提现金额。 |
| Body | `feeMinor` | number | 否 | 提现手续费；客户端可传 `0`，实际冻结和手续费以服务端提现逻辑为准。 |
| Body | `payoutProvider` | string | 否 | 收款方式：`BANK` 或 `EWALLET`。为空时服务端兼容使用用户最近的收款资料。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `withdrawId` | string | 是 | 提现单 ID。 |
| `status` | string | 是 | 提现状态。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/withdraw/apply' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","amountMinor":100000,"feeMinor":0,"payoutProvider":"BANK"}'
```

#### GET /api/v1/withdraw/records

接口作用：查询提现记录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |
| Query | `offset` | number | 否 | 分页偏移。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].id` | string | 是 | 提现记录 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].userId` | string | 是 | 用户 ID。 |
| `[].amountMinor` | number | 是 | 提现金额。 |
| `[].feeMinor` | number | 是 | 手续费。 |
| `[].currency` | string | 是 | 币种。 |
| `[].status` | string | 是 | 状态。 |
| `[].payoutProvider` | string | 否 | 出款渠道。 |
| `[].rejectReason` | string | 否 | 驳回原因。 |
| `[].createdAt` | string | 否 | 创建时间。 |
| `[].updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/withdraw/records?userId=usr_xxx&limit=50&offset=0'
```

### 13.5 用户、团队与升级接口

#### GET /api/v1/users/{userId}/profile

接口作用：查询用户资料。`/api/v1/users/me` 和 `/api/v1/users/current` 当前用于兼容 H5，参数为 `userId` query。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | string | 是 | 用户 ID。 |
| `countryCode` | string | 是 | 国家码。 |
| `displayName` | string | 是 | 显示名。 |
| `phone` | string | 否 | 手机号。 |
| `whatsappNumber` | string | 否 | WhatsApp 号码。 |
| `nickname` | string | 否 | 昵称。 |
| `avatarUrl` | string | 否 | 头像 URL。 |
| `referralCode` | string | 否 | 邀请码。 |
| `parentUserId` | string | 否 | 上级用户 ID。 |
| `rootUserId` | string | 否 | 根用户 ID。 |
| `relationLevel` | number | 否 | 关系层级。 |
| `role` | string | 否 | `USER`、`AGENT`、`PARTNER`。 |
| `starLevel` | number | 否 | 星级。 |
| `status` | string | 否 | 用户状态。 |
| `riskLevel` | string | 否 | 风险等级。 |
| `createdAt` | string | 否 | 创建时间。 |
| `updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/users/usr_xxx/profile'
```

#### PUT /api/v1/users/{userId}/profile

接口作用：更新用户资料。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| Body | `nickname` | string | 否 | 昵称。 |
| Body | `avatarUrl` | string | 否 | 头像 URL。 |

返回参数：同 `UserProfile`。

调用示例：

```bash
curl -X PUT 'https://api-id-test.beexofficial.com/api/v1/users/usr_xxx/profile' \
  -H 'Content-Type: application/json' \
  -d '{"nickname":"BeeX User","avatarUrl":"https://example.com/avatar.png"}'
```

#### POST /api/v1/users/{userId}/avatar

接口作用：上传头像文件。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| FormData | `file` | File | 是 | 头像文件。 |

返回参数：同 `UserProfile`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/users/usr_xxx/avatar' \
  -F 'file=@avatar.png'
```

#### GET /api/v1/growth/users/{userId}/role

接口作用：查询当前用户角色和星级。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | string | 是 | 用户 ID。 |
| `countryCode` | string | 是 | 国家码。 |
| `role` | string | 是 | `USER`、`AGENT`、`PARTNER`。 |
| `starLevel` | number | 是 | 星级。 |
| `status` | string | 是 | 角色状态。 |
| `effectiveAt` | string | 否 | 生效时间。 |
| `updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/role'
```

#### GET /api/v1/growth/users/{userId}/relation

接口作用：查询当前用户的邀请关系。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 关系记录 ID。 |
| `countryCode` | string | 是 | 国家码。 |
| `userId` | string | 是 | 当前用户 ID。 |
| `parentUserId` | string | 否 | 直属上级 ID。 |
| `rootUserId` | string | 否 | 根节点用户 ID。 |
| `level` | number | 是 | 当前层级。 |
| `path` | string | 否 | 关系路径。 |
| `status` | string | 是 | 关系状态。 |
| `createdAt` | string | 否 | 创建时间。 |
| `updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/relation'
```

#### GET /api/v1/growth/users/{userId}/tree

接口作用：查询团队树，返回汇总和成员列表。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 当前用户 ID。 |
| Query | `maxDepth` | number | 否 | 查询层级，默认 `20`。 |
| Query | `limit` | number | 否 | 返回数量，默认 `100`。 |
| Query | `offset` | number | 否 | 分页偏移，默认 `0`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `summary` | TeamSummaryModel | 是 | 团队汇总。 |
| `members` | TeamMemberModel[] | 是 | 成员列表。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/tree?maxDepth=20&limit=100&offset=0'
```

#### GET /api/v1/growth/users/{userId}/ancestors

接口作用：查询当前用户上级链路。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| Query | `maxDepth` | number | 否 | 查询层级，默认 `20`。 |

返回参数：`ReferralAncestorModel[]`，包含上级用户 ID、角色、星级、层级等字段。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/ancestors?maxDepth=20'
```

#### GET /api/v1/growth/users/{userId}/children

接口作用：查询直属下级成员。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 当前用户 ID。 |
| Query | `limit` | number | 否 | 返回数量，默认 `50`。 |
| Query | `offset` | number | 否 | 分页偏移，默认 `0`。 |

返回参数：`TeamMemberModel[]`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/children?limit=50&offset=0'
```

#### GET /api/v1/growth/users/{userId}/network-overview

接口作用：查询我的推广联盟页汇总、角色统计和分页成员列表。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 当前用户 ID。 |
| Query | `maxDepth` | number | 否 | 查询下级层级，默认 `20`。 |
| Query | `limit` | number | 否 | 本页数量，默认 `20`。 |
| Query | `offset` | number | 否 | 分页偏移，默认 `0`。 |
| Query | `role` | string | 否 | 成员角色筛选：`USER`、`AGENT`、`PARTNER`。 |
| Query | `starLevel` | number | 否 | 星级筛选。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `summary.totalMembers` | number | 是 | 团队总人数。 |
| `summary.estimatedIncomeMinor` | number | 是 | 预估联盟收入。 |
| `summary.actualIncomeMinor` | number | 是 | 已到账联盟收入。 |
| `summary.salesCommissionMinor` | number | 是 | 销售佣金。 |
| `summary.totalCashbackMinor` | number | 是 | 总返现联盟。 |
| `summary.userCount` | number | 是 | User 数量。 |
| `summary.agentCount` | number | 是 | Agent 数量。 |
| `summary.partnerCount` | number | 是 | Partner 数量。 |
| `summary.agentStarCounts` | object | 是 | Agent 星级数量。 |
| `summary.partnerStarCounts` | object | 是 | Partner 星级数量。 |
| `members[]` | TeamMemberWithIncome[] | 是 | 当前页成员列表。 |
| `members[].userId` | string | 是 | 成员用户 ID。 |
| `members[].nickname` | string | 否 | 昵称。 |
| `members[].avatarUrl` | string | 否 | 头像。 |
| `members[].role` | string | 是 | 角色。 |
| `members[].starLevel` | number | 是 | 星级。 |
| `members[].estimatedCashbackMinor` | number | 是 | 该成员贡献的预估收益。 |
| `members[].settledCashbackMinor` | number | 是 | 该成员贡献的已到账收益。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/network-overview?maxDepth=20&limit=20&offset=0&role=AGENT&starLevel=1'
```

#### GET /api/v1/growth/users/{userId}/descendants

接口作用：分页查询下级成员。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 当前用户 ID。 |
| Query | `maxDepth` | number | 否 | 查询层级。 |
| Query | `limit` | number | 否 | 本页数量。 |
| Query | `offset` | number | 否 | 分页偏移。 |

返回参数：`TeamMemberModel[]`，字段包括 `userId`、`parentUserId`、`depth`、`nickname`、`avatarUrl`、`role`、`starLevel`、`joinedAt`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/descendants?maxDepth=20&limit=50&offset=0'
```

#### GET /api/v1/growth/users/{userId}/team-summary

接口作用：查询团队汇总。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 当前用户 ID。 |
| Query | `maxDepth` | number | 否 | 查询层级。 |

返回参数：`TeamSummaryModel`，包括团队总数、User/Agent/Partner 数量及星级统计。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/team-summary?maxDepth=20'
```

#### GET /api/v1/growth/users/{userId}/children-earnings

接口作用：查询下级成员及其贡献收益。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 当前用户 ID。 |
| Query | `maxDepth` | number | 否 | 查询层级，默认 `1`。 |
| Query | `limit` | number | 否 | 本页数量。 |
| Query | `offset` | number | 否 | 分页偏移。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].member` | TeamMemberModel | 是 | 下级成员。 |
| `[].estimatedRebateMinor` | number | 是 | 预估贡献收益。 |
| `[].settledRebateMinor` | number | 是 | 已到账贡献收益。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/children-earnings?maxDepth=1&limit=100&offset=0'
```

#### GET /api/v1/growth/users/{userId}/free-partner-upgrade

接口作用：查询当前 Agent 是否满足免费升级 Partner 条件。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | string | 是 | 用户 ID。 |
| `eligible` | boolean | 是 | 是否满足免费升级条件。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/free-partner-upgrade'
```

#### POST /api/v1/growth/users/{userId}/free-partner-upgrade

接口作用：领取免费升级 Partner，服务端完成角色变更和奖励发放。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |

返回参数：同 `UserRoleModel`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/growth/users/usr_xxx/free-partner-upgrade' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

#### GET /api/v1/rebate-fund/users/{userId}

接口作用：查询用户返佣基金状态；无记录时返回 `null`。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `userId` | string | 是 | 用户 ID。 |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 基金记录 ID。 |
| `countryCode` | string | 是 | 国家码。 |
| `userId` | string | 是 | 用户 ID。 |
| `inviterUserId` | string | 否 | 上级用户 ID。 |
| `totalMinor` | number | 是 | 基金总额。 |
| `remainingMinor` | number | 是 | 剩余额度。 |
| `ruleCode` | string | 是 | 规则编码。 |
| `status` | string | 是 | 状态。 |
| `validFrom` | string | 否 | 生效时间。 |
| `validTo` | string | 否 | 失效时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/rebate-fund/users/usr_xxx?countryCode=ID'
```

#### POST /api/v1/rebate-fund/claim

接口作用：用户领取返佣基金；若用户无上线且 `inviterCode` 有效，服务端先补绑上线再发放基金。`inviterCode` 为空或无效时仍会按“无上线”发放基金，业务侧如需强制邀请码必须在前端或后续服务端规则中收紧。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `inviterCode` | string | 否 | 团长邀请码。 |

返回参数：同 `RebateFundGrant`，无可发放记录时返回 `null`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/rebate-fund/claim' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","inviterCode":"BEE123"}'
```

#### GET /api/v1/growth/invites/{referralCode}/preview

接口作用：预览邀请码是否可用、升级优惠和推荐奖励。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `referralCode` | string | 是 | 邀请码。 |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Query | `userId` | string | 否 | 被邀请用户 ID，用于校验自邀/已绑定。 |
| Query | `courseCode` | string | 否 | 课程编码，优先按课程价目计算折扣。 |
| Query | `courseAmountMinor` | number | 否 | 课程金额；旧客户端兼容字段。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `referralCode` | string | 是 | 邀请码。 |
| `valid` | boolean | 是 | 邀请码是否存在。 |
| `discountEligible` | boolean | 是 | 当前用户是否可享优惠。 |
| `inviterUserId` | string | 否 | 邀请人 ID。 |
| `inviterName` | string | 否 | 邀请人名称。 |
| `inviterRole` | string | 否 | 邀请人角色。 |
| `inviterStarLevel` | number | 是 | 邀请人星级。 |
| `inviterParentUserId` | string | 否 | 邀请人的直属上级 ID；存在时才计算间接推荐奖励金额。 |
| `inviteeDiscountBps` | number | 是 | 被邀请人优惠比例，按课程原价计算。 |
| `inviteeDiscountMinor` | number | 是 | 被邀请人优惠金额。 |
| `payableAmountMinor` | number | 是 | 应付金额。 |
| `directRewardBps` | number | 是 | 直属推荐奖励比例，来自 `COURSE_DIRECT` 规则。 |
| `directRewardAmountMinor` | number | 是 | 直属推荐奖励金额。 |
| `indirectRewardBps` | number | 是 | 间接推荐奖励比例，来自 `COURSE_INDIRECT` 规则。 |
| `indirectRewardAmountMinor` | number | 是 | 间接推荐奖励金额。 |
| `reason` | string | 是 | 校验原因。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/growth/invites/BEE123/preview?countryCode=ID&userId=usr_xxx&courseCode=AGENT_STARTER'
```

#### GET /api/v1/course-plans

接口作用：查询升级课程/套餐价目。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].courseCode` | string | 是 | 课程编码。 |
| `[].courseName` | string | 是 | 课程名。 |
| `[].selfPayPriceMinor` | number | 是 | 原价。 |
| `[].invitedPriceMinor` | number | 是 | 使用邀请码价。 |
| `[].roleAfterPaid` | string | 是 | 支付后角色。 |
| `[].starAfterPaid` | number | 是 | 支付后星级。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/course-plans?countryCode=ID'
```

#### POST /api/v1/course-orders

接口作用：创建课程/升级订单，同时创建支付单。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `courseCode` | string | 是 | 课程编码。 |
| Body | `courseName` | string | 是 | 课程名。 |
| Body | `amountMinor` | number | 是 | 实付金额。 |
| Body | `roleAfterPaid` | string | 否 | 支付后角色：`AGENT` 或 `PARTNER`。 |
| Body | `starAfterPaid` | number | 否 | 支付后星级。 |
| Body | `inviteReferralCode` | string | 否 | 邀请码。 |
| Body | `couponId` | string | 否 | 优惠券 ID。 |
| Body | `successRedirectUrl` | string | 否 | 支付成功回跳地址。 |
| Body | `failureRedirectUrl` | string | 否 | 支付失败回跳地址。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `courseOrder` | CourseOrder | 是 | 课程订单。 |
| `payment` | PaymentResponse | 是 | 支付单。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/course-orders' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","courseCode":"AGENT_STARTER","courseName":"Agent Starter","amountMinor":100000,"roleAfterPaid":"AGENT","starAfterPaid":1}'
```

#### GET /api/v1/course-orders/{id}

接口作用：查询单个课程订单。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 课程订单 ID。 |

返回参数：`CourseOrder`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/course-orders/cor_xxx'
```

#### GET /api/v1/course-orders

接口作用：查询用户课程订单列表。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |

返回参数：`CourseOrder[]`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/course-orders?userId=usr_xxx&limit=20'
```

### 13.6 支付接口

#### POST /api/v1/payments/create

接口作用：创建通用支付单，当前用于钱包充值、课程订单等业务。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `bizType` | string | 是 | `WALLET_TOP_UP`、`COURSE_ORDER`、`TRAVEL_ORDER`、`SERVICE_FEE`。 |
| Body | `bizId` | string | 否 | 业务单 ID。 |
| Body | `amountMinor` | number | 是 | 支付金额。 |
| Body | `description` | string | 否 | 支付描述。 |
| Body | `successRedirectUrl` | string | 否 | 成功回跳地址。 |
| Body | `failureRedirectUrl` | string | 否 | 失败回跳地址。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `paymentOrderId` | string | 是 | 支付单 ID。 |
| `externalId` | string | 是 | 外部 ID。 |
| `bizType` | string | 是 | 业务类型。 |
| `provider` | string | 是 | `MOCK` 或 `XENDIT`。 |
| `providerPaymentId` | string | 否 | 三方支付 ID。 |
| `currency` | string | 是 | 币种。 |
| `amountMinor` | number | 是 | 支付金额。 |
| `feeMinor` | number | 是 | 手续费。 |
| `status` | string | 是 | `CREATED`、`PENDING`、`PAID`、`EXPIRED`、`FAILED`、`CANCELLED`。 |
| `checkoutUrl` | string | 否 | 支付跳转地址。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/payments/create' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","bizType":"WALLET_TOP_UP","amountMinor":100000,"description":"BeeX wallet top up"}'
```

#### GET /api/v1/payments/{id}

接口作用：查询支付单状态。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 支付单 ID。 |

返回参数：同 `PaymentResponse`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/payments/pay_xxx'
```

#### POST /api/v1/payments/{id}/mock-paid

接口作用：测试环境模拟支付成功。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 支付单 ID。 |

返回参数：同 `PaymentResponse`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/payments/pay_xxx/mock-paid' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### 13.7 优惠券、活动与奖励接口

#### GET /api/v1/coupons

接口作用：查询用户券包。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].id` | string | 是 | 券 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].userId` | string | 是 | 用户 ID。 |
| `[].couponType` | string | 是 | 券类型。 |
| `[].rewardMode` | string | 否 | 奖励模式。 |
| `[].claimMode` | string | 否 | 领取模式。 |
| `[].title` | string | 是 | 券标题。 |
| `[].factorBps` | number | 是 | 倍率/比例基点。 |
| `[].amountMinor` | number | 是 | 固定金额。 |
| `[].minOrderMinor` | number | 否 | 使用门槛。 |
| `[].maxDiscountMinor` | number | 否 | 最大优惠。 |
| `[].currency` | string | 否 | 币种。 |
| `[].status` | string | 是 | 券状态。 |
| `[].expiresAt` | string | 否 | 过期时间。 |
| `[].sourceType` | string | 否 | 来源类型。 |
| `[].sourceId` | string | 否 | 来源 ID。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/coupons?userId=usr_xxx&limit=50'
```

#### GET /api/v1/coupons/{id}

接口作用：查询单张优惠券详情。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 券 ID。 |

返回参数：同 `UserCoupon`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/coupons/cpn_xxx'
```

#### POST /api/v1/coupons/{id}/claim

接口作用：领取可领取券。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `id` | string | 是 | 券 ID。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `sourceType` | string | 否 | 领取来源类型。 |
| Body | `sourceId` | string | 否 | 领取来源 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `claimed` | boolean | 是 | 是否领取成功。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/coupons/cpn_xxx/claim' \
  -H 'Content-Type: application/json' \
  -d '{"userId":"usr_xxx","sourceType":"H5_COUPON_CENTER","sourceId":"usr_xxx"}'
```

#### POST /api/v1/coupons/preview

接口作用：预览优惠券对订单、升级套餐等业务金额的影响。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `bizType` | string | 是 | 业务类型，例如 `AFFILIATE_ORDER`、`COURSE_ORDER`。 |
| Body | `amountMinor` | number | 是 | 原始金额。 |
| Body | `couponId` | string | 否 | 指定券 ID；不传由服务端按规则预览。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `couponId` | string | 否 | 命中的券 ID。 |
| `discountMinor` | number | 否 | 优惠金额。 |
| `payableAmountMinor` | number | 否 | 应付金额。 |
| `rewardAmountMinor` | number | 否 | 奖励金额。 |
| `available` | boolean | 否 | 是否可用。 |
| `reason` | string | 否 | 不可用原因。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/coupons/preview' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","bizType":"AFFILIATE_ORDER","amountMinor":83800000,"couponId":"cpn_xxx"}'
```

#### GET /api/v1/activity-campaigns/cards

接口作用：查询首页 Banner、商品详情活动卡片、活动弹窗展示数据。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `userId` | string | 否 | 用户 ID。 |
| Query | `deviceId` | string | 否 | 设备 ID。 |
| Query | `fileName` | string | 否 | 文件名。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].campaignId` | string | 是 | 活动 ID。 |
| `[].campaignCode` | string | 是 | 活动编码。 |
| `[].title` | string | 是 | 标题。 |
| `[].subtitle` | string | 否 | 副标题。 |
| `[].description` | string | 否 | 描述。 |
| `[].cardImageUrl` | string | 否 | 卡片图。 |
| `[].cardTheme` | string | 否 | 主题。 |
| `[].targetRoles` | string | 否 | 目标角色。 |
| `[].newUserOnly` | boolean | 是 | 是否仅新用户。 |
| `[].priority` | number | 是 | 排序优先级。 |
| `[].effectiveFrom` | string | 是 | 生效时间。 |
| `[].effectiveTo` | string | 否 | 失效时间。 |
| `[].rules[]` | object[] | 是 | 活动规则。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/activity-campaigns/cards?countryCode=ID&userId=usr_xxx'
```

#### GET /api/v1/campaigns/placements

接口作用：查询首页 Banner、活动弹窗、悬浮入口等活动运营位配置。当前首页使用 `HOME_BANNER`、`HOME_POPUP`、`HOME_FLOATING_ENTRY`。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `placements` | string | 是 | 逗号分隔展示位，例如 `HOME_BANNER,HOME_POPUP,HOME_FLOATING_ENTRY`。 |
| Query | `userId` | string | 否 | 当前用户 ID。 |
| Query | `role` | string | 否 | 当前角色，用于筛选活动。 |
| Query | `appVersion` | string | 否 | App 版本，用于版本定向。 |
| Query | `environmentId` | string | 否 | 环境 ID，用于环境定向。 |
| Query | `limit` | number | 否 | 单次返回数量，默认 `100`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `placements` | object | 是 | 按展示位分组的活动配置。 |
| `placements.HOME_BANNER[]` | object[] | 否 | 首页 Banner 配置列表。 |
| `placements.HOME_POPUP[]` | object[] | 否 | 首页弹窗配置列表。 |
| `placements.HOME_FLOATING_ENTRY[]` | object[] | 否 | 首页悬浮入口配置列表。 |
| `placements.*[].id` | string | 是 | 展示位配置 ID。 |
| `placements.*[].countryCode` | string | 是 | 国家码。 |
| `placements.*[].name` | string | 是 | 活动配置名称。 |
| `placements.*[].placement` | string | 是 | 展示位。 |
| `placements.*[].status` | string | 是 | `DRAFT`、`ACTIVE`、`DISABLED`。 |
| `placements.*[].priority` | number | 是 | 优先级，数值越大越靠前。 |
| `placements.*[].startAt` | string | 是 | 生效时间。 |
| `placements.*[].endAt` | string | 否 | 失效时间。 |
| `placements.*[].audienceRule` | object | 否 | 人群规则。 |
| `placements.*[].content` | object | 是 | 展示内容。 |
| `placements.*[].action` | object | 是 | 点击动作。 |
| `placements.*[].frequencyRule` | object | 否 | 频控规则。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/campaigns/placements?countryCode=ID&placements=HOME_BANNER,HOME_POPUP,HOME_FLOATING_ENTRY&userId=usr_xxx&role=USER&environmentId=id-test'
```

#### GET /api/v1/admin/campaign-placements

接口作用：管理后台分页查询活动坑位配置。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码。 |
| Query | `placement` | string | 否 | 展示位。 |
| Query | `status` | string | 否 | `DRAFT`、`ACTIVE`、`DISABLED`。 |
| Query | `keyword` | string | 否 | 按名称搜索。 |
| Query | `pageNo` | number | 否 | 页码。 |
| Query | `pageSize` | number | 否 | 每页数量。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `records[]` | object[] | 是 | 活动坑位配置列表，字段同 `CampaignPlacement`。 |
| `pageNo` | number | 是 | 页码。 |
| `pageSize` | number | 是 | 每页数量。 |
| `total` | number | 是 | 总数。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/admin/campaign-placements?countryCode=ID&placement=HOME_BANNER&status=ACTIVE&pageNo=1&pageSize=20'
```

#### GET /api/v1/admin/campaign-placements/{id}

接口作用：管理后台查询单个活动坑位配置。

返回参数：`CampaignPlacement`。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/admin/campaign-placements/cpl_home_banner_001'
```

#### POST /api/v1/admin/campaign-placements

接口作用：管理后台创建活动坑位配置。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `name` | string | 是 | 配置名称。 |
| Body | `placement` | string | 是 | 展示位。 |
| Body | `status` | string | 否 | `DRAFT`、`ACTIVE`、`DISABLED`，不传默认为 `DRAFT`。 |
| Body | `priority` | number | 是 | 优先级。 |
| Body | `startAt` | string | 是 | 生效时间。 |
| Body | `endAt` | string | 否 | 失效时间。 |
| Body | `audienceRule` | object | 否 | 人群规则。 |
| Body | `content` | object | 是 | 展示内容。 |
| Body | `action` | object | 是 | 点击动作。 |
| Body | `frequencyRule` | object | 否 | 频控规则。 |

返回参数：`CampaignPlacement`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/admin/campaign-placements' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","name":"新用户首单活动","placement":"HOME_BANNER","status":"ACTIVE","priority":10,"startAt":"2026-06-01T00:00:00+07:00","content":{"title":"首单立返","imageUrl":"https://cdn.example.com/campaign/home-banner.png","buttonText":"查看活动"},"action":{"type":"ROUTE","target":"/coupons"}}'
```

#### PUT /api/v1/admin/campaign-placements/{id}

接口作用：管理后台更新活动坑位配置。

请求参数同 `POST /api/v1/admin/campaign-placements`，返回参数为更新后的 `CampaignPlacement`。

#### POST /api/v1/admin/campaign-placements/{id}/enable

接口作用：启用活动坑位配置。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `updated` | boolean | 是 | 是否更新成功。 |

#### POST /api/v1/admin/campaign-placements/{id}/disable

接口作用：停用活动坑位配置。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `updated` | boolean | 是 | 是否更新成功。 |

#### DELETE /api/v1/admin/campaign-placements/{id}

接口作用：删除活动坑位配置。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `deleted` | boolean | 是 | 是否删除成功。 |

#### GET /api/v1/admin/campaign-placements/options

接口作用：查询后台配置枚举，供管理后台下拉框使用。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `placements[]` | string[] | 是 | 展示位枚举。 |
| `statuses[]` | string[] | 是 | 状态枚举。 |

#### POST /api/v1/admin/campaign-placements/{id}/preview

接口作用：管理后台预览指定用户是否命中活动坑位。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `userId` | string | 否 | 用户 ID。 |
| Body | `role` | string | 否 | 用户角色。 |
| Body | `appVersion` | string | 否 | App 版本。 |
| Body | `environmentId` | string | 否 | 环境 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `matched` | boolean | 是 | 是否命中。 |
| `placement` | object | 否 | 命中的活动坑位配置。 |

#### GET /api/v1/admin/rewards/rules

接口作用：查询旧表 `reward_rule_config` 中的奖励规则。当前业务优先读取 `rule_config_versions` 的 `ruleType=reward` 生效版本；旧表用于兼容或兜底。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Query | `platform` | string | 否 | 平台码，例如 `TIKTOK`、`SHOPEE`；不传查询全平台规则。 |

返回参数：`RewardRuleModel[]`。

#### POST /api/v1/admin/rewards/rules

接口作用：写入旧表奖励规则。新业务规则版本应优先使用 `/api/v1/admin/config/rule-versions` 创建和发布。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `id` | string | 否 | 规则 ID；不传由服务端生成。 |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `platform` | string | 否 | 平台码；为空表示全平台默认规则。 |
| Body | `ruleType` | string | 是 | 奖励规则类型，见下方 `reward.rules[]` 说明。 |
| Body | `factorBps` | number | 否 | 比例 BPS。 |
| Body | `fixedAmountMinor` | number | 否 | 固定奖励金额。 |
| Body | `releaseDelayDays` | number | 否 | 释放延迟天数。 |
| Body | `enabled` | boolean | 否 | 是否启用，不传默认 `true`。 |
| Body | `effectiveFrom` | string | 否 | 生效时间，不传为当前时间。 |
| Body | `effectiveTo` | string | 否 | 失效时间。 |

返回参数：`RewardRuleModel`。

#### POST /api/v1/rewards/commissions/release-due

接口作用：释放已到 `releaseAt` 的待结算佣金，通常由系统任务或后台手动触发。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `limit` | number | 否 | 单次释放数量，默认 `200`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `releasedCount` | number | 是 | 本次释放成功的佣金记录数。 |

#### POST /api/v1/rewards/team-commissions/settle

接口作用：按月结任务制结算指定 Partner 的团队佣金。服务端按 `statMonth` 汇总该 Partner 本人及团队范围内完成订单的平台佣金 M，先乘 `DIRECT_COMMISSION` 得到团队 base 直佣，再乘 `TEAM_COMMISSION` 生成一条月度 `TEAM_COMMISSION` 佣金记录；稳定 ID 保证同一 `leaderUserId + statMonth` 幂等。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Query | `leaderUserId` | string | 是 | 要结算团队佣金的 Partner 用户 ID。 |
| Query | `statMonth` | string | 是 | 统计月份，格式 `yyyy-MM`，例如 `2026-05`。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `leaderUserId` | string | 是 | Partner 用户 ID。 |
| `statMonth` | string | 是 | 统计月份。 |
| `platformCommissionMinor` | number | 是 | 团队范围内完成订单的平台佣金 M 汇总。 |
| `baseDirectCommissionMinor` | number | 是 | 按 `DIRECT_COMMISSION` 计算出的团队 base 直佣。 |
| `teamCommissionMinor` | number | 是 | 按 `TEAM_COMMISSION` 计算出的团队月结佣金。 |
| `teamGmvMinor` | number | 是 | 团队范围内完成订单 GMV，用于任务门槛判断。 |
| `teamOrderCount` | number | 是 | 团队范围内完成订单数，用于任务门槛判断。 |
| `activeUserCount` | number | 是 | 团队范围内有完成订单的用户数，用于任务门槛判断。 |
| `created` | boolean | 是 | 本次是否新建佣金记录；重复结算时为 `false`。 |

#### GET /api/v1/admin/config/rule-versions

接口作用：管理后台分页查询业务规则版本。用于佣金、提现、券、活动、关系等业务规则的版本化配置，不用于 Banner/弹窗等运营展示位。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Query | `ruleType` | string | 否 | 规则类型，例如 `reward`、`withdraw`、`coupon`。 |
| Query | `status` | string | 否 | `DRAFT`、`ACTIVE`、`DISABLED`。 |
| Query | `pageNo` | number | 否 | 页码。 |
| Query | `pageSize` | number | 否 | 每页数量。 |

返回参数：分页 `RuleConfigVersion`。

#### POST /api/v1/admin/config/rule-versions

接口作用：创建业务规则版本草稿。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Body | `ruleType` | string | 是 | 规则类型。 |
| Body | `version` | string | 是 | 业务版本号。 |
| Body | `status` | string | 否 | 不传默认为 `DRAFT`。 |
| Body | `effectiveAt` | string | 否 | 生效时间；不传为当前时间。 |
| Body | `expiredAt` | string | 否 | 失效时间。 |
| Body | `config` | object | 否 | 规则 JSON 内容。 |
| Body | `createdBy` | string | 否 | 创建人。 |

返回参数：`RuleConfigVersion`。

`ruleType=reward` 时，`config` 使用 `rules` 数组。业务侧读取奖励规则时会优先读取当前 `ACTIVE` 且生效中的规则版本；同一个 `ruleType` 下，指定 `platform` 的规则优先于 `platform=null` 的全平台规则；未配置的奖励规则继续回落到旧的 `reward_rule_config`。

`reward.rules[]` 字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `platform` | string/null | 否 | 平台码，例如 `TIKTOK`、`SHOPEE`、`LAZADA`；`null` 表示全平台默认规则。 |
| `ruleType` | string | 是 | 奖励规则类型，例如 `USER_CASHBACK`、`DIRECT_COMMISSION`、`INDIRECT_COMMISSION`、`TEAM_COMMISSION`、`COURSE_DIRECT`、`COURSE_INDIRECT`、`TPB`、`TPB_AGENT_STAR_UPGRADE`、`REBATE_FUND`。旧枚举 `MENTOR_COMMISSION`、`COURSE_MENTOR` 仅作为历史兼容。 |
| `factorBps` | number | 否 | 比例，基于 BPS，`7000` 表示 70%。 |
| `fixedAmountMinor` | number | 否 | 固定奖励金额，minor 单位；大于 0 时按固定额发放。 |
| `releaseDelayDays` | number | 否 | 奖励释放天数。 |
| `enabled` | boolean | 否 | 是否启用，不传默认 `true`；`false` 时业务侧忽略该规则。 |

`reward.teamTask` 字段用于配置团队佣金月结任务门槛；不传时服务端按全 0 默认值处理，即只要求受益人是 ACTIVE Partner。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `enabled` | boolean | 否 | 是否启用团队佣金月结任务，默认 `true`。 |
| `minTeamGmvMinor` | number | 否 | 团队月 GMV 最低门槛，minor 单位，默认 `0`。 |
| `minTeamOrderCount` | number | 否 | 团队月完成订单数最低门槛，默认 `0`。 |
| `minActiveUserCount` | number | 否 | 团队月有完成订单用户数最低门槛，默认 `0`。 |

当前业务接入状态：

- `USER_CASHBACK`：用户购物返现，按订单时间命中规则。
- `DIRECT_COMMISSION`：直属上级销售佣金，按订单时间命中规则。
- `INDIRECT_COMMISSION`：上上级/Partner 间接佣金，按订单时间命中规则。
- `TEAM_COMMISSION`：团队佣金，订单阶段不实时发放；由 `/api/v1/rewards/team-commissions/settle` 按月汇总团队 base 直佣后结算。
- `COURSE_DIRECT`：课程直属推荐奖励的历史比例规则；当前发放优先使用 `INVITE_DIRECT_PARTNER` / `INVITE_DIRECT_AGENT` 固定额，缺配时才回退该规则。
- `COURSE_INDIRECT`：课程间接推荐奖励的历史比例规则；当前发放优先使用 `INVITE_INDIRECT_PARTNER` / `INVITE_INDIRECT_AGENT` 固定额，缺配时才回退该规则。
- `TPB`：下属 Partner 升星/升 Partner 的培育奖，默认固定额 `500000`。
- `TPB_AGENT_STAR_UPGRADE`：下属 Agent 升星的培育奖，默认固定额 `200000`；缺配时服务端按该默认值兜底。
- `REBATE_FUND`：新用户返现基金；`fixedAmountMinor` 覆盖基金发放额度，`factorBps` 覆盖订单抵扣比例，旧 `rebate_fund_config` 仍提供有效期和取整配置。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/admin/config/rule-versions' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","ruleType":"reward","version":"2026-06-a","effectiveAt":"2026-06-05T00:00:00","config":{"rules":[{"platform":null,"ruleType":"USER_CASHBACK","factorBps":6000,"releaseDelayDays":30},{"platform":null,"ruleType":"DIRECT_COMMISSION","factorBps":1200,"releaseDelayDays":30},{"platform":null,"ruleType":"INDIRECT_COMMISSION","factorBps":240,"releaseDelayDays":30},{"platform":null,"ruleType":"TEAM_COMMISSION","factorBps":2000,"releaseDelayDays":30},{"platform":null,"ruleType":"COURSE_DIRECT","factorBps":1000,"releaseDelayDays":30},{"platform":null,"ruleType":"COURSE_INDIRECT","factorBps":500,"releaseDelayDays":30},{"platform":null,"ruleType":"TPB","factorBps":0,"fixedAmountMinor":500000,"releaseDelayDays":30},{"platform":null,"ruleType":"TPB_AGENT_STAR_UPGRADE","factorBps":0,"fixedAmountMinor":200000,"releaseDelayDays":30},{"platform":null,"ruleType":"REBATE_FUND","factorBps":1000,"fixedAmountMinor":50000000,"releaseDelayDays":30},{"platform":null,"ruleType":"INVITE_DIRECT_PARTNER","factorBps":0,"fixedAmountMinor":150000,"releaseDelayDays":30},{"platform":null,"ruleType":"INVITE_DIRECT_AGENT","factorBps":0,"fixedAmountMinor":60000,"releaseDelayDays":30},{"platform":null,"ruleType":"INVITE_INDIRECT_PARTNER","factorBps":0,"fixedAmountMinor":75000,"releaseDelayDays":30},{"platform":null,"ruleType":"INVITE_INDIRECT_AGENT","factorBps":0,"fixedAmountMinor":30000,"releaseDelayDays":30},{"platform":null,"ruleType":"TEAM_LEAD","factorBps":0,"fixedAmountMinor":500000,"releaseDelayDays":30}],"teamTask":{"enabled":true,"minTeamGmvMinor":0,"minTeamOrderCount":0,"minActiveUserCount":0}},"createdBy":"admin"}'
```

#### PUT /api/v1/admin/config/rule-versions/{id}

接口作用：更新业务规则版本。请求参数同 `POST /api/v1/admin/config/rule-versions`。

#### POST /api/v1/admin/config/rule-versions/{id}/publish

接口作用：发布业务规则版本。发布时同一 `countryCode + ruleType` 不能存在生效时间重叠的 `ACTIVE` 版本。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `approvedBy` | string | 否 | 审批人。 |

返回参数：发布后的 `RuleConfigVersion`。

#### POST /api/v1/admin/config/rule-versions/{id}/disable

接口作用：停用业务规则版本。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `updated` | boolean | 是 | 是否更新成功。 |

#### GET /api/v1/admin/config/runtime-features

接口作用：管理后台分页查询 App/H5 运行开关。运行开关会合并到 `GET /api/v1/app/runtime-config` 的 `features` 中。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Query | `clientType` | string | 否 | 客户端类型，例如 `APP`、`ANDROID`、`IOS`、`H5`。 |
| Query | `featureKey` | string | 否 | 功能 key。 |
| Query | `pageNo` | number | 否 | 页码。 |
| Query | `pageSize` | number | 否 | 每页数量。 |

返回参数：分页 `RuntimeFeatureConfig`。

#### POST /api/v1/admin/config/runtime-features

接口作用：创建运行开关配置。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 否 | 国家码，默认 `ID`。 |
| Body | `clientType` | string | 否 | 客户端类型，默认 `APP`。 |
| Body | `featureKey` | string | 是 | 功能 key，例如 `cashbackClipboardDetect`。 |
| Body | `enabled` | boolean | 否 | 是否启用，不传默认为 `true`。 |
| Body | `environmentId` | string | 否 | 环境 ID；为空表示所有环境。 |
| Body | `minAppVersion` | string | 否 | 最低 App 版本。 |
| Body | `maxAppVersion` | string | 否 | 最高 App 版本。 |
| Body | `config` | object | 否 | 扩展配置。 |

返回参数：`RuntimeFeatureConfig`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/admin/config/runtime-features' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","clientType":"APP","featureKey":"cashbackClipboardDetect","enabled":true,"environmentId":"id-test","minAppVersion":"1.0.0","config":{}}'
```

#### PUT /api/v1/admin/config/runtime-features/{id}

接口作用：更新运行开关配置。请求参数同 `POST /api/v1/admin/config/runtime-features`。

#### DELETE /api/v1/admin/config/runtime-features/{id}

接口作用：删除运行开关配置。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `deleted` | boolean | 是 | 是否删除成功。 |

#### GET /api/v1/activity-campaigns/rewards

接口作用：查询活动奖励记录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |

返回参数：`ActivityRewardRecord[]`，字段以后端返回为准。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/activity-campaigns/rewards?userId=usr_xxx&limit=50'
```

#### GET /api/v1/tpb-rewards

接口作用：查询 TPB 奖励记录。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |
| Query | `limit` | number | 否 | 返回数量。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].id` | string | 是 | 奖励 ID。 |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].userId` | string | 是 | 用户 ID。 |
| `[].statMonth` | string | 是 | 统计月份。 |
| `[].baseAmountMinor` | number | 是 | 基础金额。 |
| `[].multiplierBps` | number | 是 | 倍率基点。 |
| `[].rewardAmountMinor` | number | 是 | 奖励金额。 |
| `[].status` | string | 是 | 状态。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/tpb-rewards?userId=usr_xxx&limit=12'
```

### 13.8 返现申诉、App 配置、日志与推送接口

#### POST /api/v1/cashback-appeals/attachments

接口作用：上传返现问题申诉截图。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `userId` | string | 是 | 用户 ID。 |
| FormData | `file` | File | 是 | 截图文件，支持图片格式，最大 10MB。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `fileUrl` | string | 是 | 上传后的文件 URL。 |
| `fileType` | string | 是 | 文件类型，例如 `IMAGE`。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/cashback-appeals/attachments?countryCode=ID&userId=usr_xxx' \
  -F 'file=@order.png'
```

#### POST /api/v1/cashback-appeals

接口作用：提交返现问题申诉。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `platform` | string | 是 | 平台。 |
| Body | `purchasedAt` | string | 是 | 购买时间。 |
| Body | `platformOrderId` | string | 是 | 平台订单号。 |
| Body | `whatsappNumber` | string | 否 | 联系 WhatsApp。 |
| Body | `description` | string | 否 | 问题描述。 |
| Body | `attachmentUrls` | string[] | 否 | 截图 URL 列表。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 申诉 ID。 |
| `status` | string | 是 | 初始为 `SUBMITTED`。 |
| `createdAt` | string | 是 | 创建时间。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/cashback-appeals' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","platform":"TIKTOK","purchasedAt":"2026-06-01T18:30:00","platformOrderId":"123456789","description":"订单已完成但未到账","attachmentUrls":["https://example.com/order.png"]}'
```

#### GET /api/v1/countries

接口作用：查询 App 支持的国家列表。

请求参数：无。

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `[].countryCode` | string | 是 | 国家码。 |
| `[].name` | string | 否 | 国家名称。 |
| `[].currency` | string | 否 | 币种。 |
| `[].locale` | string | 否 | 默认语言区域。 |
| `[].enabled` | boolean | 否 | 是否启用。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/countries'
```

#### GET /api/v1/app/runtime-config

接口作用：查询 App/H5 运行时配置。返回固定运行参数，并合并管理后台 `runtime_feature_config` 中命中的功能开关。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码，不传默认为 `ID`。 |
| Query | `platform` | string | 否 | 平台，例如 `ANDROID`、`IOS`、`H5`。 |
| Query | `appVersion` | string | 否 | App 版本。 |
| Query | `buildNumber` | string | 否 | 构建号。 |
| Query | `packageName` | string | 否 | App 包名，用于判断 App Link 入口是否启用。 |
| Query | `environmentId` | string | 否 | 环境 ID，用于匹配运行开关。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `countryCode` | string | 否 | 国家码。 |
| `platform` | string | 否 | 平台。 |
| `appVersion` | string | 否 | App 版本。 |
| `buildNumber` | string | 否 | 构建号。 |
| `packageName` | string | 否 | App 包名。 |
| `apiBaseUrl` | string | 否 | API Base URL。 |
| `h5BaseUrl` | string | 否 | H5 Base URL。 |
| `appLinkApiHost` | string | 否 | App Link API Host。 |
| `linkBaseUrl` | string | 否 | 默认链接 Base URL。 |
| `features.appLinkEntry` | boolean | 否 | 是否启用 App Link 入口。 |
| `features.*` | boolean | 否 | 管理后台配置的运行开关，按国家、平台、环境和版本过滤。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/app/runtime-config?countryCode=ID&platform=ANDROID&appVersion=1.0.0&environmentId=id-test'
```

#### GET /api/v1/app/h5-package/latest

接口作用：App 查询当前环境最新 H5 包。无更新时 `hasUpdate=false`，其余下载字段为空。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 否 | 国家码。 |
| Query | `envCode` | string | 否 | 环境编码，例如 `id-test`。 |
| Query | `platform` | string | 否 | 平台，例如 `ANDROID`、`IOS`。 |
| Query | `nativeVersion` | string | 否 | 原生 App 版本。 |
| Query | `buildNumber` | string | 否 | 构建号。 |
| Query | `packageName` | string | 否 | App 包名。 |
| Query | `currentH5Version` | string | 否 | 当前本地 H5 版本。 |
| Query | `deviceId` | string | 否 | 设备 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `hasUpdate` | boolean | 是 | 是否有可用更新。 |
| `h5Version` | string | 否 | 最新 H5 版本；无更新时返回当前版本。 |
| `packageUrl` | string | 否 | H5 包下载地址。 |
| `packageSize` | number | 否 | 包大小。 |
| `sha256` | string | 否 | 包 SHA-256。 |
| `signature` | string | 否 | 签名。 |
| `entry` | string | 否 | H5 入口文件。 |
| `minNativeVersion` | string | 否 | 最低原生版本。 |
| `maxNativeVersion` | string | 否 | 最高原生版本。 |
| `forceUpdate` | boolean | 是 | 是否强制更新。 |
| `releaseNotes` | string | 否 | 发布说明。 |

#### POST /api/v1/app/h5-package/report

接口作用：App 上报 H5 包下载、应用或失败结果。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 否 | 国家码。 |
| Body | `envCode` | string | 否 | 环境编码。 |
| Body | `platform` | string | 否 | 平台。 |
| Body | `nativeVersion` | string | 否 | 原生 App 版本。 |
| Body | `buildNumber` | string | 否 | 构建号。 |
| Body | `packageName` | string | 否 | App 包名。 |
| Body | `userId` | string | 否 | 用户 ID。 |
| Body | `deviceId` | string | 否 | 设备 ID。 |
| Body | `oldH5Version` | string | 否 | 更新前 H5 版本。 |
| Body | `newH5Version` | string | 否 | 更新后 H5 版本。 |
| Body | `eventType` | string | 否 | 事件类型，例如 `DOWNLOAD_SUCCESS`、`APPLY_SUCCESS`、`FAILED`。 |
| Body | `errorMessage` | string | 否 | 失败原因。 |

返回参数：`H5PackageUpdateLog`。

#### GET /api/v1/app-logs/upload-token

接口作用：获取 App 日志或附件上传凭证。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `userId` | string | 否 | 用户 ID。 |
| Query | `deviceId` | string | 否 | 设备 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `endpoint` | string | 否 | OSS endpoint。 |
| `bucket` | string | 否 | OSS bucket。 |
| `region` | string | 否 | OSS region。 |
| `accessKeyId` | string | 否 | 临时访问 key。 |
| `accessKeySecret` | string | 否 | 临时访问 secret。 |
| `securityToken` | string | 否 | 临时安全 token。 |
| `expiration` | string | 否 | 凭证过期时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/app-logs/upload-token?countryCode=ID&userId=usr_xxx'
```

#### GET /api/v1/app-logs/sls-token

接口作用：获取 SLS 日志上传临时凭证。当前线上日志未上传到 SLS 时，客户端可保留封装但不强依赖。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `countryCode` | string | 是 | 国家码。 |
| Query | `userId` | string | 否 | 用户 ID。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `endpoint` | string | 否 | SLS endpoint。 |
| `project` | string | 否 | SLS project。 |
| `logstore` | string | 否 | SLS logstore。 |
| `accessKeyId` | string | 否 | 临时访问 key。 |
| `accessKeySecret` | string | 否 | 临时访问 secret。 |
| `securityToken` | string | 否 | 临时安全 token。 |
| `expiration` | string | 否 | 凭证过期时间。 |

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/app-logs/sls-token?countryCode=ID&userId=usr_xxx'
```

#### POST /api/v1/app-logs/feedback

接口作用：提交 App 日志反馈。该接口只用于日志反馈，不用于返现业务申诉。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 否 | 用户 ID。 |
| Body | `deviceId` | string | 否 | 设备 ID。 |
| Body | `appVersion` | string | 否 | App 版本。 |
| Body | `content` | string | 是 | 反馈内容。 |
| Body | `contact` | string | 否 | 联系方式。 |
| Body | `attachments` | string[] | 否 | 附件 URL。 |
| Body | `logs` | object | 否 | 客户端日志上下文。 |

返回参数：无业务 `data`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/app-logs/feedback' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","content":"debug feedback","contact":"whatsapp_xxx"}'
```

#### POST /api/v1/push/devices/register

接口作用：注册 App 推送设备。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `deviceId` | string | 是 | 设备 ID。 |
| Body | `platform` | string | 是 | `IOS`、`ANDROID`、`WEB`。 |
| Body | `pushToken` | string | 是 | 推送 token。 |
| Body | `appVersion` | string | 否 | App 版本。 |
| Body | `buildNumber` | string | 否 | 构建号。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 否 | 设备记录 ID。 |
| `userId` | string | 是 | 用户 ID。 |
| `countryCode` | string | 否 | 国家码。 |
| `deviceId` | string | 是 | 设备 ID。 |
| `platform` | string | 否 | 平台。 |
| `pushToken` | string | 否 | 推送 token。 |
| `enabled` | boolean | 否 | 是否启用。 |
| `createdAt` | string | 否 | 创建时间。 |
| `updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/push/devices/register' \
  -H 'Content-Type: application/json' \
  -d '{"countryCode":"ID","userId":"usr_xxx","deviceId":"device_xxx","platform":"ANDROID","pushToken":"push_token"}'
```

#### POST /api/v1/push/devices/disable

接口作用：禁用推送设备。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `userId` | string | 是 | 用户 ID。 |
| Body | `deviceId` | string | 否 | 设备 ID。 |
| Body | `pushToken` | string | 否 | 推送 token。 |

返回参数：无业务 `data`。

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/push/devices/disable' \
  -H 'Content-Type: application/json' \
  -d '{"userId":"usr_xxx","deviceId":"device_xxx"}'
```

#### GET /api/v1/push/devices

接口作用：查询用户已注册的推送设备。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Query | `userId` | string | 是 | 用户 ID。 |

返回参数：`PushDevice[]`，字段同 `POST /api/v1/push/devices/register` 返回。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/push/devices?userId=usr_xxx'
```

#### POST /api/v1/push/notifications/users

接口作用：向指定用户创建推送任务。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Body | `countryCode` | string | 是 | 国家码。 |
| Body | `userIds` | string[] | 是 | 接收用户 ID 列表。 |
| Body | `title` | string | 是 | 推送标题。 |
| Body | `body` | string | 是 | 推送内容。 |
| Body | `data` | object | 否 | 跳转参数或扩展数据。 |

返回参数：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `taskId` | string | 是 | 推送任务 ID。 |
| `status` | string | 是 | 任务状态。 |
| `total` | number | 否 | 目标总数。 |
| `sent` | number | 否 | 已发送数。 |
| `failed` | number | 否 | 失败数。 |
| `createdAt` | string | 否 | 创建时间。 |
| `updatedAt` | string | 否 | 更新时间。 |

调用示例：

```bash
curl -X POST 'https://api-id-test.beexofficial.com/api/v1/push/notifications/users' \
  -H 'Content-Type: application/json' \
  -d '{"userIds":["usr_xxx"],"title":"BeeX","body":"You have a new reward"}'
```

#### GET /api/v1/push/tasks/{taskId}

接口作用：查询推送任务执行状态。

请求参数：

| 参数位置 | 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| Path | `taskId` | string | 是 | 推送任务 ID。 |

返回参数：同 `POST /api/v1/push/notifications/users` 返回。

调用示例：

```bash
curl 'https://api-id-test.beexofficial.com/api/v1/push/tasks/task_xxx'
```