# 宝箱活动接口

**treasure_box**

宝箱活动的 `list` / `detail` / `claim` 走通用活动接口（`kind=treasure_box`，详见 [活动接口](400_promotion.md)）。本章只补充宝箱专有的玩家端接口与数据结构。

---

## 活动详情字段 {#detail}

通用接口 `GET /promotion/treasure_box/detail` 的 `data` 字段：

字段 | 类型 | 说明
---|---|---
description | string | 活动说明
share_text | string | 分享文案
main_image_url | string | 活动主图
share_show_phone | bool | 分享是否显示手机号
bet_multiple | number | 宝箱奖励对应的打码倍数
effective_recharge_threshold | number | 邀请人达标的累计充值门槛
effective_bet_threshold | number | 邀请人达标的累计有效投注门槛
pending_count | number | 当前未领取宝箱数量
pending_amount | number | 当前未领取金额合计
effective_count | number | 已达标邀请人数（用于 `tiers` 进度）
next_tier | object / null | 尚未达到的下一档 `{effective_count, amount}`；按有效邀请人数与已发宝箱最高门槛的较大值计算，已达最高档或未配置档位时为 `null`，不因领取或过期而回退
tiers | list<Tier\> | 宝箱档位列表

`Tier` 字段：

字段 | 类型 | 说明
---|---|---
effective_count | number | 该档位累计已发宝箱数门槛
amount | number | 命中后该宝箱锁定金额
box | object / null | 该档位当前玩家的宝箱实例；没有实例时为 `null`

活动列表 `/promotion/list` 的该活动 `data[].payload` 下发 `next_tier`，与详情口径一致。

`Box` 字段：

字段 | 类型 | 说明
---|---|---
id | string | 宝箱 ID
amount | number | 金额
bet_multiple | number | 打码倍数
expire_at | string | 过期时间（RFC3339）
status | number | `0` 待领取 / `1` 已领取 / `2` 已过期
claimed_at | string | 领取时间（RFC3339），未领取为空串

---

## 领取宝箱 {#claim}

通用接口 `POST /promotion/treasure_box/claim`。

**输入:**

字段 | 类型 | 必填 | 说明
---|---|---|---
box_id | string | 否 | 指定宝箱 ID；为空则一次性领取所有未过期 pending 宝箱（聚合一次入账）

**输出:**

字段 | 类型 | 说明
---|---|---
amount | number | 本次领取金额合计（保留两位小数）
claimed_box_ids | list<string\> | 本次领取的宝箱 ID 列表

---

## 邀请人列表 {#invitees}

返回当前玩家名下最多 200 条邀请人记录，按创建时间倒序。活动未启用时返回错误。

读取时服务端会顺带评估名下未达标邀请（达标即实时发箱、刷新累充/累投快照），同一玩家 30 秒内最多触发一次评估，其余请求直读快照。

**URL:** `GET` /treasure_box/invitees

**Query:**

字段 | 类型 | 必填 | 说明
---|---|---|---
only_valid | bool | 否 | `true` 时只返回有效用户（status ≠ 2），默认返回全部

**输出:**

字段 | 类型 | 说明
---|---|---
data.list | list<object\> | 邀请人记录列表

单项字段：

字段 | 类型 | 说明
---|---|---
member_id | string | 被邀请会员 ID
username | string | 被邀请会员用户名
status | number | `0` 未达标 / `1` 已达标已发箱 / `2` 达标但被规则拒
skipped_reason | string | 拒绝原因，`""` / `same_ip_cap` / `tier_overflow`
recharge_amount | number | 累计充值
bet_amount | number | 累计有效投注
effective_recharge_threshold | number | 充值达标阈值（快照）
effective_bet_threshold | number | 投注达标阈值（快照）
created_at | string | 记录创建时间（RFC3339）