# 返水接口

**rakeback**

返水活动的 `list` / `detail` / `claim` 走通用活动接口（`kind=rakeback`，详见 [活动接口](400_promotion.md)）。

**自然日结算（`daily_settle=true`）**：
- **今日预览**（`today_bet` / `today_amount`）直接读注单明细，投注结算后几秒内可见（最多约 10 秒缓存）。
- **昨天（商户时区）的待领**：日界线后 10 秒起，会员当天第一次访问（`list` / `detail` / 红点 / `claim`）时就地结算并立即可见；仍在领取期内的更早日子若漏结算，同一次访问一并补齐。没有后台批量任务，会员不访问就不产生开销。日界线刚过的几秒内，晚结算的注单可能不计入昨天。
- `claim_deadline` 为该待领记录的截止时间，逾期不可领。

---

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

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

字段 | 类型 | 说明
---|---|---
description | string | 活动说明
bet_multiple | number | 打码倍数
min_claim_amount | number | 最低领取门槛
tier_index | number | 当前档位下标，未达任何档位时为 `-1`
rate_percent | number | 当前档位的返水百分比
lifetime_bet | number | 自注册以来累计有效投注
today_bet | number | 本自然日有效投注
today_amount | number | 本自然日返水预览金额
daily_settle | boolean | 自然日结算开关状态
pending_bet | number | 当前待领取投注基数
claimable_amount | number | 当前可领取返水金额
claim_rate_percent | number | 待领取记录使用的返水比例
claim_amount | number | 待领取记录的返水金额
claim_bet_basis | number | 待领取记录的投注基数
claim_tier_index | number | 待领取记录命中的档位下标；无待领取记录时为 `-1`
claim_period_key | string | 待领取记录对应的商户自然日（`YYYY-MM-DD`）
claim_deadline | string | 当前待领取记录的截止时间（RFC3339），未配置有效期或无待领记录时为空串
last_claim_at | string | 上次领取时间（RFC3339），从未领取为空串
tiers | list<Tier\> | 档位列表（来自配置）

`Tier` 字段：

字段 | 类型 | 说明
---|---|---
threshold | number | 档位投注门槛
rate_percent | number | 返水百分比

未登录或会员不存在时各动态字段为零值。

---

## 领取 {#claim}

通用接口 `POST /promotion/rakeback/claim`。后端通过 Redis 锁防双击，命中条件：达到至少一档 + `claimable_amount >= min_claim_amount`。

**输入:** `{}`

**输出:**

字段 | 类型 | 说明
---|---|---
amount | number | 入账金额
tier_index | number | 命中档位下标
rate_percent | number | 命中档位的返水百分比
bet_basis | number | 本次结算的 `pending_bet`
bet_multiple | number | 打码倍数