# 兑换码接口

**redeem_code**

兑换码活动允许玩家提交一段字符串兑换码，后端校验通过后将奖励直接入账钱包，并写入一条领取流水。本章描述玩家端兑换接口。

---

## 兑换码兑换 {#redeem}

玩家提交兑换码字符串，后端按下列顺序校验：

1. 兑换码是否存在（大小写敏感）
2. 兑换码当前是否在有效期内
3. 玩家是否符合该兑换码的领取人群条件
4. 玩家是否已领取过该兑换码

校验通过后入账并记录领取结果。双钱包版本中，有打码要求的奖励计入奖金余额 `bonus_money` 并建立任务，无码奖励计入现金余额 `user_money`；倍数和 `can_abandon` 按该兑换码的配置在发奖时固化，放弃权限从 [任务列表](201_wager_tasks.md#list) 读取，不由兑换响应返回。

**完成本次兑换的任务不代表立即能提现**：仍须全部待完成任务及旧打码清零，见 [活动奖励通用规则](400_promotion.md#wager_rules)。兑换码的有效期是领取期限，不是已入账任务的有效期。

**URL:** `POST` /promotion/redeem_code/claim

**输入:**

字段 | 类型 | 必填 | 说明
---|---|---|---
code | string | 是 | 兑换码字符串，最大 64 字符，大小写敏感

**输出:**

字段 | 类型 | 说明
---|---|---
amount | number | 实际入账金额
bet_multiple | int | 该笔奖励的打码倍数；`0` 为无码奖励，非零时以生成任务的 `target_amount` 为准，不代表全账户提现门槛
message | string | 固定为 `兑换成功`

**业务错误（`code != 0`）：**

message | 触发条件
---|---
请先登录 | 当前请求未携带有效 JWT 或玩家身份缺失
兑换码不能为空 | `code` 字段为空
兑换码不存在或已失效 | 后端未找到对应兑换码，或已被禁用
兑换码不在有效期内 | 当前时间不在兑换码配置的生效时间窗口内
您不符合本兑换码的领取条件 | 当前玩家不满足兑换码绑定的人群条件
您已领取过该兑换码 | 同一玩家对同一兑换码重复提交
兑换码领取人数已达上限 | 该兑换码总领取数已达到运营配置的上限，无法再领

**请求示例：**

```bash
curl -X POST 'https://<game-domain>/api/game/promotion/redeem_code/claim' \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"code":"WELCOME2026"}'
```

**成功响应示例：**

```json
{
  "code": 0,
  "data": {
    "amount": 10.00,
    "bet_multiple": 3,
    "message": "兑换成功"
  }
}
```