# 首充奖励接口

**first_recharge_bonus**

首充奖励的 `list` / `detail` 走通用活动接口（`kind=first_recharge_bonus`，详见 [活动接口](400_promotion.md)）。**奖励由充值订单（`source=first_recharge_bonus`）支付成功后自动发放**，玩家端不需要也无法手动领取（`POST /promotion/first_recharge_bonus/claim` 始终返回错误「首充奖励由充值订单自动发放」）。本章仅描述 detail 字段。

**活动可见性与参赛资格**：**只要没参加过（未领取过首充奖励）就可以参加，与历史充值无关**；已领取过的玩家不再可见、不再弹窗。游客（未登录）始终可见。商户将活动停用后，【[站点配置](500_site_content.md#config)】的 `popups` 也不再下发 `first_recharge_bonus`。

玩家在充值时选择参加本活动（充值下单传 `source=first_recharge_bonus`），支付成功后服务端按充值金额命中的**最高档位**自动发放加赠。加赠可配置为**固定金额**或**按充值金额比例**（见 `bonus_type`）。每人仅一次。

---

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

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

字段 | 类型 | 说明
---|---|---
description | string | 活动说明
is_active | bool | 活动是否开启（商户后台启用且已配置档位）。**本接口免登录且不受活动开关拦截**，关闭时仍会正常返回，需自行据此字段隐藏入口
can_join | bool | 当前玩家是否可参加（= `is_active` 且 `status != 2`）。**充值页直接用这一个字段**决定要不要展示「参加首充活动」选项；未登录时等同于 `is_active`
status | number | 玩家领取状态：`0` 未领（首充后自动发放）/ `2` 已领取
bonus | number | 已领取的加赠金额（`status=2` 时有效）
current_recharge | number | 玩家累计充值金额（`total_deposit_amount`）；未登录时为 `0`。仅供展示，不影响参赛资格
recommended_tier_index | number | 推荐档位下标（0-based，商户后台配置），前端弹窗默认选中该档；服务端已对越界/无档位场景归一为 `0`，前端可直接使用
min_tier_threshold | number | 最低档位充值门槛（即 `tiers[0].min_amount`），无档位时为 `0`
bonus_type | string | 加赠方式：`fixed` 固定金额 / `percent` 按充值金额比例。**前端据此决定展示 `tiers[].bonus` 还是 `tiers[].bonus_percent`**
max_bonus | number | 加赠上限（元），`0` 表示不限。**`bonus_type=percent` 时必须参与计算**：实发加赠 = `min(充值金额 × bonus_percent ÷ 100（向下取整到分）, max_bonus)`，否则玩家充得越多展示值会越偏离实发金额
tiers | list<Tier\> | 加赠档位列表

`Tier` 字段：

字段 | 类型 | 说明
---|---|---
min_amount | number | 充值门槛（≥ 该值命中该档）
bonus | number | 加赠金额（`bonus_type=fixed` 时生效）
bonus_percent | number | 加赠比例（%，`bonus_type=percent` 时生效）；实际加赠 = 充值金额 × 该比例，向下取整到分，并受 `max_bonus` 封顶
bet_multiple | number | 该档加赠对应的打码倍数

未登录或会员不存在时，`status` 为 `0`、`bonus` 为 `0`。