优惠券模块 — 移动端接口文档

模块：business-coupon（入口在 business-mobile-gateway）
前缀：${jeesharp.web.mobilePath}（默认 /mobile）
更新日期：2026-06-05

一、接口规范

1.1 请求头（登录接口）

Content-Type: application/json;charset=UTF-8
access_token: {token}
X-Platform: MINI | APP | H5
X-Device-Id: {deviceId}

1.2 响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": { },
  "requestId": "uuid-xxx"
}

二、会员优惠券（核心）`member/coupon`

Controller：CouponMobileController
基础路径：/mobile/member/coupon

2.1 可领取优惠券列表

URL：POST /available

认证：需要登录

{
"pageNo": 1,
"pageSize": 10,
"couponName": "",
"couponType": 1
}

响应 data：

字段	说明
list	可领模板列表
totalCount	总数
pageNo / pageSize	分页

list 项：templateId、couponName、couponType、discountValue、validStartDate、validEndDate、remainCount、isReceived 等。

2.2 领取优惠券

URL：POST /receive
```
{ "templateId": "模板ID" }
```

2.3 我的优惠券

URL：POST /my 或 POST /myList

{
"pageNo": 1,
"pageSize": 10,
"status": 0
}

status：0未用 1已用 2过期 3冻结 4作废。

2.4 优惠券详情

URL：GET /detail?couponId={会员券ID}

2.5 卡面详情（与领券中心 UI 一致）

URL：GET /walletDetail?memberCouponId={id}

2.6 订单可用优惠券（试算列表）⭐

URL：POST /usable
说明：结算页展示可用/不可用券及预估抵扣

当前请求体：

{
  "orderAmount": 299.00
}

当前响应 data：

{
  "usableCoupons": [
    {
      "memberCouponId": "…",
      "couponName": "…",
      "minConsumeAmount": 100,
      "estimatedDiscount": 20.00
    }
  ],
  "unusableCoupons": [
    {
      "memberCouponId": "…",
      "couponName": "…",
      "reason": "未满最低消费100元"
    }
  ]
}

规划扩展（见 doc/优惠券架构设计.md）：

{
  "sceneCode": "MALL",
  "platform": "MINI",
  "orderAmount": 299.00,
  "scopeItemIds": ["spuId1", "spuId2"]
}

2.7 积分兑换

URL：POST /exchange
```
{ "templateId": "模板ID" }
```

三、优惠券模板（规范路径）`coupon/couponTemplate`

Controller：CouponTemplateMobileController
基础路径：/mobile/coupon/couponTemplate

方法	URL	说明
POST	`/list`	进行中模板分页
GET	`/info?id=`	模板详情

四、领券中心（免登录浏览）`coupon`

Controller：CouponCatalogMobileController
路径：/mobile/coupon（白名单，前端须 skipAuth: true）

方法	URL	说明
GET	`/templates`	可浏览模板列表
GET	`/template/{id}`	模板详情

五、业务线结账对接说明

移动端 不直接调用 冻结/核销接口；由业务订单接口在服务端编排：

阶段	负责方	券模块方法（服务端）
结算页拉券	各业务结算 API 或统一转发	`usableForOrder` → 目标 `listForCheckout`
下单试算	商城/酒店下单 API	`resolveMallCouponDiscount` → 目标 `resolveDiscount`
下单冻结	创建订单事务内	`freezeForMallOrder` → 目标 `freezeForOrder`
支付成功	支付回调	`confirmMallOrderCouponPaid` → 目标 `confirmOrderPaid`

C 端只需：结算页调 可用券列表 + 提交订单时传 memberCouponId（字段名以各业务订单 DTO 为准）。

六、状态码

code	说明
200	成功
201	需要登录
203	参数错误
202	服务器错误

券业务常见错误：优惠券不存在、未满最低消费、优惠券不可用、优惠券抵扣金额已变化，请重新选择。

七、已知限制（与架构文档对齐）

/usable 未按 sceneCode、商品 ID 过滤，多场景上线前须升级接口。
/my、/detail 部分字段（如 useScope）仍为占位，待返回真实场景与范围文案。
仅 商城订单 服务端完整走冻结/核销；酒店/美食结算须按架构文档接入。

八、更新日志

版本	日期	说明
1.0	2026-05-07	领券、我的券、usable 试算
1.1	2026-06-05	补充架构对接说明与接口演进规划

移动端接口文档.md 4.6 KB Permalink History Raw