优惠活动 (Promotions & Activities)

概述

• 接口说明：获取当前玩家可参与的优惠活动列表，并提供优惠详情与申请入口。

底层业务逻辑与说明 (Business Logic)

WARNING

优惠活动不仅仅是纯粹的展示，它深度绑定了玩家的钱包流水与防刷机制。在转化为 API 时必须遵循以下规则：

1. 参数加密传递：下发可参与的优惠列表时，系统不会返回明文的 promo_id，而是返回由 Sha256 封转的 Token（如 sha256('deposit' + id)）。客户端申请优惠时必须提交该 Token，防止被爬虫或脚本恶意遍历 id 刷单。
2. 多维度防刷 (Restriction Types 1-5)：
   • Type 1 & 2：每日限领一次。
   • Type 3：每周限领一次。
   • Type 4：每月限领一次。
   • Type 5：仅限后台指定的特定周几参与（Specific Days）。
3. 同组互斥 (Group Restrictions)：若多个优惠活动被配置为同一个 group_id，则上述防刷限制将作用于整个组。例如今天领了组内活动 A，将无法再领组内活动 B。
4. 无感自动派发 (Auto Assign)：若活动配置了 promo_autoassign = 1，则无需玩家主动调用申请接口。系统将在玩家完成注册 (promo_deposit_type = 1) 或 日常充值 (promo_deposit_type != 1) 且满足特定等级要求时，自动将红利派发至账户。
5. 流水强绑：领取优惠后，后台会计算 turnover (流水要求) 并累加到钱包的 sum_winover 中。未达标前拦截一切提现请求。

---

1. GET - 获取优惠活动列表

• 路径: /api/promotions/list

请求 Header

参数名	类型	必填	说明
Authorization	String	否	Bearer Token (未登录时仅返回公共活动，不包含专属计算)

响应示例

{
  "code": 0,
  "msg": "Success",
  "data": [
    {
      "title": "Welcome Bonus 100%",
      "promo_token": "a1b2c3d4e5f6g7h8i9j0...", // 供后续申请使用的加密 Token
      "min_topup": 50.00,
      "max_topup": 1000.00,
      "banner_url": "https://api.domain.com/images/banner1.webp",
      "auto_assign": false
    }
  ]
}

2. GET - 获取优惠详情

• 路径: /api/promotions/detail

请求参数

参数名	类型	必填	说明
promo_token	String	是	从列表获取的加密 Token

响应示例

{
  "code": 0,
  "msg": "Success",
  "data": {
    "title": "Welcome Bonus 100%",
    "description": "<p>Here is the html detail of the promo...</p>",
    "end_date": "2026-12-31 23:59:59"
  }
}

3. POST - 申请优惠 (结合充值)

NOTE

通常优惠活动是在“提交充值订单”时，通过附带 promo_token 参数一并提交的。如果存在免充值的免费礼金活动，才会单独调用此接口。

• 路径: /api/promotions/claim

请求参数

参数名	类型	必填	说明
promo_token	String	是	从列表获取的加密 Token

响应示例

{
  "code": 0,
  "msg": "Promotion claimed successfully",
  "data": {
    "bonus_amt": 50.00,
    "turnover_required": 1000.00
  }
}