# 通行证活动接口

**battle_pass**

通行证活动的 `list` / `detail` / `claim` / `purchase` 走通用活动接口（`kind=battle_pass`，详见 [活动接口](400_promotion.md)）。本章只描述通行证特有的 `detail` 数据结构与 `claim` / `purchase` 输入输出。

---

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

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

字段 | 类型 | 说明
---|---|---
description | string | 活动说明
cycle_key | string | 当前周期标识（如 `2026-06`，延展周期带 `+ext` 后缀）
start_at | string | 当前周期开始时间（RFC3339）
end_at | string | 当前周期结束时间（RFC3339）
is_extended | bool | 当前周期是否为注册尾段延展周期
is_premium | bool | 当前玩家是否已购买高级版
premium_price | number | 高级版购买价格
tail_extension_days | number | 临近月末注册自动延展的天数
red_packet_is_icon | string | `0` / `1` 是否有 icon 图
red_packet_icon | string | icon URL
nodes | list<Node\> | 节点进度列表

`Node` 字段：

字段 | 类型 | 说明
---|---|---
id | string | 节点 ID
kind | string | 节点 kind：`login_days` / `deposit_amount` / `bet_amount`
threshold | number | 达成阈值
progress | number | 当前玩家在本周期的实时进度
reached | bool | 是否已达成阈值
free_reward | object | 免费轨道奖励 `{amount, bet_multiple}`
free_claimed | bool | 免费轨道是否已领取
premium_reward | object | 高级轨道奖励 `{amount, bet_multiple}`
premium_claimed | bool | 高级轨道是否已领取

---

## 领取节点奖励 {#claim}

通用接口 `POST /promotion/battle_pass/claim`。同一 track 上节点必须按顺序领取，前序未领时拒绝跳领。

**输入:**

字段 | 类型 | 必填 | 说明
---|---|---|---
node_id | string | 是 | 节点 ID
track | string | 是 | `free` 或 `premium`，`premium` 需先购买高级版

**输出:**

字段 | 类型 | 说明
---|---|---
amount | number | 入账金额
bet_multiple | number | 打码倍数
node_id | string | 节点 ID
track | string | `free` / `premium`

---

## 购买高级版 {#purchase}

通用接口 `POST /promotion/battle_pass/purchase`。每周期仅可购买一次。

**输入:** 无

**输出:**

字段 | 类型 | 说明
---|---|---
id | string | 购买记录 ID
price | number | 实际扣费金额
cycle_key | string | 所属周期标识