极客场馆开放平台 · 钱包接口

版本 v1 · 配套文档：加密与签名接入 · 通用约定与错误码 所有路径前缀 https://www.gymker.com/api/open/v1。响应/错误码/幂等/限流见通用约定。

---

1. 能力总览

能力	scope	典型用途
查储值余额	wallet:read	下单页展示可用余额
储值流水	wallet:read	对账 / 排查扣款
小额扣款	wallet:deduct	商城/自助机用余额支付（单笔 ≤ 500 元）
扣款冲正	wallet:deduct	外部下单失败回滚原扣款

---

2. 查储值余额 · GET /wallets/{memberId}

scope wallet:read。

本金（self） = 会员真实付款部分；赠送（gift） = 活动奖励部分。两者额度独立、合并可用，扣款顺序由后端 FIFO 自动决定。

{
  "memberId": 12345, "gymId": 1001,
  "selfBalance": 1200.00, "giftBalance": 300.00, "total": 1500.00,
  "selfFrozen": 0.00, "giftFrozen": 0.00
}

---

3. 储值流水 · GET /wallets/{memberId}/transactions

scope wallet:read。Query：startDate / endDate / page / size（跨度 ≤ 90 天）。

扣款按 FIFO（先进先出） 消耗余额，不是按比例分摊：一笔业务可能只动本金、只动赠送、或跨越两者。仅当跨越时才会产生 self / gift 两条流水。按业务汇总时用 bizNo 合并即可。

data.records[] 单元素：

{
  "id": 99999, "memberId": 12345, "bizType": "OPEN_API_DEDUCT",
  "bizNo": "gk_open_xxx:ext-mall-20260527-0001",
  "direction": "out", "amountType": "self", "amount": 88.00,
  "balanceAfter": 1112.00, "relatedOrderType": null, "relatedOrderId": null,
  "remark": "购买 ProteinBar x2", "occurredAt": "2026-05-27T10:00:00"
}

---

4. 小额扣款 · POST /wallets/{memberId}/deduct ⭐

scope wallet:deduct。请求 body：

{
  "outBizNo": "ext-mall-20260527-0001",
  "amount": 88.00,
  "remark": "购买 ProteinBar x2",
  "extra": { "skuId": "sku_001", "extOrderId": "M2026052700001" }
}

字段	类型	必填	说明
outBizNo	string	是	外部业务单号，幂等键。(AppId, outBizNo) 唯一，重试必须复用
amount	decimal	是	金额（元，2 位小数），> 0，单笔上限 500 元（超出返 50002）。余额不足返 50001，不部分扣
remark	string	是	用途备注（必填），写入流水，便于门店与对接方对账
extra	object	否	透传字段，不参与业务逻辑

响应 data：

{
  "outBizNo": "ext-mall-20260527-0001",
  "selfDeducted": 88.00, "giftDeducted": 0.00, "totalDeducted": 88.00,
  "selfBalanceAfter": 1112.00, "giftBalanceAfter": 300.00,
  "idempotent": false, "occurredAt": "2026-05-27T10:00:00"
}

业务规则：

1. 单笔金额 > 500 元直接返 50002（开放平台只做小额扣划，不做制单 / 核销）
2. 余额不足返 50001，不部分扣
3. self / gift 扣减顺序由后端 FIFO 自动决定，对接方只传总金额
4. 同一 outBizNo 多次调用返回相同结果（幂等）；用过后换参数复用返 50002

---

5. 扣款冲正 · POST /wallets/{memberId}/deduct/{outBizNo}/reverse

外部下单失败时回滚原扣款。scope wallet:deduct。outBizNo 为原扣款单号。

• 同一 outBizNo 多次冲正只生效一次
• 按原 self / gift 比例还原
• 找不到原扣款记录直接返成功（幂等友好）

---

6. 钱包 FAQ

Q：扣款失败但不确定余额变没变？ 用 GET /wallets/{memberId}/transactions 按 bizNo（格式 <AppId>:<outBizNo>）反查；或直接用同一 outBizNo 重试 deduct，幂等会返原结果。

Q：本金和赠送能分别扣吗？ 不能。后端 FIFO 自动决定，外部强制指定会破坏门店核算口径。只传总金额。

Q：为什么扣款限 500 元？ 开放平台只开放小额扣划场景（如商城/自助机小额消费），不开放制单与课程核销。大额请走门店正常制单流程。