钱包模块

3.1 余额查询

查询账户余额

GET /api/v1/wallet/balance

{
  "code": 0,
  "data": {
    "balance": "128.50",
    "gift_balance": "20.00",
    "total_balance": "148.50",
    "frozen_balance": "0.00",
    "currency": "CNY"
  }
}

字段	说明
`balance`	实账余额（充值获得，可提现）
`gift_balance`	赠送余额（代金券/活动赠送，不可提现）
`total_balance`	可用总余额
`frozen_balance`	冻结余额（处理中的退款等）

余额变动历史

GET /api/v1/wallet/balance/history

查询参数	类型	说明
`type`	string	`recharge` / `consume` / `gift` / `refund`
`start_date`	string	开始日期 `YYYY-MM-DD`
`end_date`	string	结束日期
`page`	int	页码
`page_size`	int	每页条数

3.2 充值

发起充值

POST /api/v1/wallet/recharge

{
  "amount": "100.00",
  "channel": "alipay",
  "return_url": "https://console.example.com/wallet",
  "client_type": "web"
}

字段	类型	必填	说明
`amount`	string	是	充值金额，最小 1.00 元
`channel`	string	是	`alipay` / `wechat` / `baofoo`
`return_url`	string	Web 必填	支付完成后跳转地址
`client_type`	string	是	`web` / `h5` / `mini_program`
`voucher_id`	string	否	使用代金券 ID

响应（支付宝 Web）：

{
  "code": 0,
  "data": {
    "order_id": "rch_20240101001",
    "channel": "alipay",
    "amount": "100.00",
    "pay_params": {
      "type": "form",
      "form_html": "<form action='https://openapi.alipay.com/...'>"
    },
    "expire_at": "2024-01-01T12:30:00Z"
  }
}

响应（微信 Web 扫码）：

{
  "code": 0,
  "data": {
    "order_id": "rch_20240101002",
    "channel": "wechat",
    "amount": "100.00",
    "pay_params": {
      "type": "qrcode",
      "code_url": "weixin://wxpay/bizpayurl?pr=xxx"
    },
    "expire_at": "2024-01-01T12:30:00Z"
  }
}

查询充值订单状态

GET /api/v1/wallet/recharge/{order_id}

{
  "code": 0,
  "data": {
    "order_id": "rch_20240101001",
    "status": "paid",
    "amount": "100.00",
    "channel": "alipay",
    "paid_at": "2024-01-01T12:05:00Z"
  }
}

status 枚举：pending / paid / cancelled / expired

支付平台异步回调

POST /api/v1/wallet/recharge/notify/{channel}

由支付平台主动回调，无需前端调用。系统验签后更新订单状态并充值。

channel 枚举：alipay / wechat / baofoo

3.3 代金券

查询代金券列表

GET /api/v1/wallet/vouchers

查询参数	说明
`status`	`available` / `used` / `expired`
`page`	页码

{
  "code": 0,
  "data": {
    "items": [
      {
        "voucher_id": "v_01HX...",
        "name": "新用户注册礼包",
        "voucher_type": "fixed_amount",
        "amount": "20.00",
        "min_recharge": "0.00",
        "status": "available",
        "applicable_models": [],
        "valid_until": "2024-12-31T23:59:59Z",
        "redeemed_at": null,
        "used_at": null
      }
    ],
    "total": 3
  }
}

兑换代金券

POST /api/v1/wallet/vouchers/redeem

{ "code": "VOUCHER2024001" }

响应：

{
  "code": 0,
  "data": {
    "voucher_id": "v_01HX...",
    "name": "新用户注册礼包",
    "amount": "20.00",
    "valid_until": "2024-12-31T23:59:59Z"
  }
}

错误码： 3101 券码无效，3102 已使用，3103 已过期

查询代金券详情

GET /api/v1/wallet/vouchers/{voucher_id}

3.4 发票申请

申请开票

POST /api/v1/wallet/invoices

{
  "order_ids": ["rch_20240101001", "rch_20240102001"],
  "invoice_type": "vat_special",
  "title": "XX 科技有限公司",
  "tax_number": "91110000XXXXXXXX",
  "bank_name": "招商银行北京分行",
  "bank_account": "0000 0000 0000 0000",
  "company_address": "北京市朝阳区XX路1号",
  "company_phone": "010-88888888",
  "email": "finance@company.com"
}

字段	说明
`invoice_type`	`vat_special` 增值税专用发票 / `vat_general` 增值税普通发票
`order_ids`	要开票的充值订单 ID 列表（需为已支付状态）