ThinkAdmin/plugin/think-plugs-wemall/readme.api.md

# 分销商城接口

## 接口标准
- HTTP 入口：`/api/wemall/{controller}/{action}`
- 公开接口：`goods/*`、`data/*`、`help/*`
- 授权接口：`/api/wemall/auth/*`，需要 `Authorization: Bearer <JWT>`
- 返回格式为 JSON
- HTTP 状态码固定返回 `200`
- `code` 统一使用常见业务状态语义：`200` 成功、`401` 未认证/登录过期、`403` 已认证但无权限、`404` 资源不存在、`500` 服务端异常

```jsonc
{
  "code": 200, // 业务状态码
  "info": "ok", // 提示信息
  "data": {}, // 业务数据
  "error": "", // 可选，401/403 等鉴权异常时返回稳定错误标识
  "token": "jwt" // 续签时可能返回，可选
}
```

## 公开接口

### `/api/wemall/goods/get`
- 说明：获取商品列表或商品详情

```jsonc
{
  "code": "", // 可选，商品编码；传值时返回单个商品详情
  "coupon": "", // 可选，优惠券编码，用于按券过滤商品
  "keys": "", // 可选，商品名称关键字
  "vmarks": "", // 可选，多标签过滤值，多个标签用逗号分隔
  "cates": "", // 可选，分类编号
  "sort": 0, // 可选，排序字段：0 默认、1 热度、2 价格
  "order": 0, // 可选，排序方向：0 倒序、1 正序
  "page": 1, // 可选，页码
  "limit": 20 // 可选，分页条数，最大 60
}
```

### `/api/wemall/goods/cate`
- 说明：获取商品分类树和标签

```jsonc
{}
```

### `/api/wemall/goods/comments`
- 说明：分页获取商品评论

```jsonc
{
  "gcode": "", // 商品编码
  "page": 1 // 页码
}
```

### `/api/wemall/goods/region`
- 说明：获取物流配送区域

```jsonc
{}
```

### `/api/wemall/goods/express`
- 说明：获取可用快递公司

```jsonc
{}
```

### `/api/wemall/goods/hotkeys`
- 说明：获取搜索热词

```jsonc
{}
```

### `/api/wemall/data/get`
- 说明：读取指定页面或配置数据

```jsonc
{
  "name": "about" // 数据名称，如 `about`、`slider`、`agreement`
}
```

### `/api/wemall/data/spread`
- 说明：识别推荐人信息

```jsonc
{
  "from": 1 // 推荐人用户 ID
}
```

### `/api/wemall/data/layout`
- 说明：获取商城布局配置

```jsonc
{}
```

### `/api/wemall/data/slider`
- 说明：获取图片内容数据

```jsonc
{
  "keys": "首页图片" // 图片分组键名
}
```

### `/api/wemall/data/agreement`
- 说明：获取隐私协议和用户协议

```jsonc
{}
```

### `/api/wemall/help/problem/get`
- 说明：获取常见问题列表

```jsonc
{
  "id": 0, // 可选，问题 ID
  "page": 1 // 可选，页码
}
```

### `/api/wemall/help/feedback/get`
- 说明：获取反馈记录

```jsonc
{
  "id": 0, // 可选，反馈 ID
  "page": 1 // 可选，页码
}
```

### `/api/wemall/help/feedback/set`
- 说明：提交反馈意见

```jsonc
{
  "phone": "13800000000", // 联系手机号
  "content": "问题描述", // 反馈内容
  "images": "url1|url2" // 可选，反馈图片，多个地址用 `|` 分隔
}
```

### `/api/wemall/help/question/get`
- 说明：获取工单列表或工单详情

```jsonc
{
  "id": 0, // 可选，工单 ID；传值时返回详情和回复
  "reply_st": 0, // 可选，回复状态筛选
  "name": "", // 可选，工单标题关键字
  "sort": "new", // 可选，排序方式：`new`、`hot`
  "page": 1 // 可选，页码
}
```

### `/api/wemall/help/question/set`
- 说明：提交工单

```jsonc
{
  "name": "订单问题", // 工单标题
  "phone": "13800000000", // 联系手机号
  "content": "问题描述", // 工单内容
  "images": "url1|url2" // 可选，附件图片，多个地址用 `|` 分隔
}
```

### `/api/wemall/help/question/reply`
- 说明：回复工单

```jsonc
{
  "ccid": 1, // 工单 ID
  "content": "补充说明", // 回复内容
  "images": "url1|url2" // 可选，回复图片
}
```

### `/api/wemall/help/question/confirm`
- 说明：确认工单已解决

```jsonc
{
  "ccid": 1 // 工单 ID
}
```

## 授权接口

### `/api/wemall/auth/cart/get`
- 说明：获取购物车数据

```jsonc
{
  "ghash": "" // 可选，商品规格哈希
}
```

### `/api/wemall/auth/cart/set`
- 说明：修改购物车商品数量

```jsonc
{
  "ghash": "SPEC_HASH", // 商品规格哈希
  "number": 1 // 购买数量
}
```

### `/api/wemall/auth/center/get`
- 说明：获取会员资料

```jsonc
{}
```

### `/api/wemall/auth/center/levels`
- 说明：获取会员等级列表

```jsonc
{}
```

### `/api/wemall/auth/center/discount`
- 说明：获取会员折扣信息

```jsonc
{}
```

### `/api/wemall/auth/checkin/add`
- 说明：执行签到

```jsonc
{}
```

### `/api/wemall/auth/checkin/get`
- 说明：获取签到记录

```jsonc
{
  "date": "2026-04" // 可选，年月筛选
}
```

### `/api/wemall/auth/checkin/config`
- 说明：获取签到配置

```jsonc
{}
```

### `/api/wemall/auth/coupon/get`
- 说明：分页获取卡券配置

```jsonc
{
  "type": "", // 可选，卡券类型
  "coid": 0, // 可选，卡券 ID
  "page": 1 // 页码
}
```

### `/api/wemall/auth/coupon/add`
- 说明：领取卡券

```jsonc
{
  "coid": 1 // 卡券配置 ID
}
```

### `/api/wemall/auth/coupon/mine`
- 说明：分页获取我的卡券

```jsonc
{
  "type": "", // 可选，卡券类型
  "coid": 0, // 可选，卡券 ID
  "status": "", // 可选，卡券状态
  "page": 1 // 页码
}
```

### `/api/wemall/auth/coupon/query`
- 说明：查询当前订单可用卡券

```jsonc
{
  "gcodes": "G001,G002", // 商品编码列表，多个编码用逗号分隔
  "amount": 0, // 订单金额
  "usable": 0, // 是否只返回当前用户可用卡券，0 否，1 是
  "level": "-", // 会员等级编码，默认 `-`
  "page": 1 // 页码
}
```

### `/api/wemall/auth/order/get`
- 说明：获取订单列表或订单详情

```jsonc
{
  "order_no": "", // 可选，订单号；传值时返回详情
  "status": "", // 可选，订单状态
  "page": 1 // 页码
}
```

### `/api/wemall/auth/order/add`
- 说明：创建订单

```jsonc
{
  "carts": "1,2,3", // 购物车 ID 列表
  "rules": "", // 直接下单时的规格规则串
  "agent": 0 // 代理升级标记或代理模式编号
}
```

### `/api/wemall/auth/order/express`
- 说明：模拟计算运费

```jsonc
{
  "order_no": "ORDER_NO", // 订单号
  "address_id": 1 // 收货地址 ID
}
```

### `/api/wemall/auth/order/perfect`
- 说明：确认收货地址

```jsonc
{
  "order_no": "ORDER_NO", // 订单号
  "address_id": 1 // 收货地址 ID
}
```

### `/api/wemall/auth/order/channel`
- 说明：获取可用支付通道

```jsonc
{}
```

### `/api/wemall/auth/order/payment`
- 说明：生成支付参数或执行余额/积分/优惠券抵扣

```jsonc
{
  "order_no": "ORDER_NO", // 订单号
  "channel_code": "wechat_jsapi", // 支付通道编码
  "balance": "0.00", // 可选，余额抵扣金额
  "integral": 0, // 可选，积分抵扣数量
  "coupon_code": "", // 可选，优惠券编码
  "order_ps": "", // 可选，订单备注
  "payment_back": "", // 可选，支付回跳地址
  "payment_image": "" // 可选，转账凭证图片
}
```

### `/api/wemall/auth/order/cancel`
- 说明：取消未支付订单

```jsonc
{
  "order_no": "ORDER_NO" // 订单号
}
```

### `/api/wemall/auth/order/remove`
- 说明：删除已取消订单

```jsonc
{
  "order_no": "ORDER_NO" // 订单号
}
```

### `/api/wemall/auth/order/confirm`
- 说明：确认收货

```jsonc
{
  "order_no": "ORDER_NO" // 订单号
}
```

### `/api/wemall/auth/order/comment`
- 说明：提交订单评论

```jsonc
{
  "order_no": "ORDER_NO", // 订单号
  "data": "{}" // 按商品规格哈希组织的评论 JSON，包含评分、内容和图片
}
```

### `/api/wemall/auth/order/total`
- 说明：获取订单状态统计

```jsonc
{}
```

### `/api/wemall/auth/order/track`
- 说明：查询物流轨迹

```jsonc
{
  "code": "express_code", // 快递公司编码
  "number": "express_no" // 快递单号
}
```

### `/api/wemall/auth/rebate/get`
- 说明：分页获取返佣记录

```jsonc
{
  "type": "", // 可选，返佣类型
  "status": "", // 可选，返佣状态
  "page": 1 // 页码
}
```

### `/api/wemall/auth/rebate/prize`
- 说明：获取我的奖励汇总

```jsonc
{}
```

### `/api/wemall/auth/rebate/prizes`
- 说明：获取奖励明细

```jsonc
{}
```

### `/api/wemall/auth/refund/get`
- 说明：获取售后单列表

```jsonc
{
  "code": "", // 可选，售后单号
  "status": "", // 可选，售后状态
  "page": 1 // 页码
}
```

### `/api/wemall/auth/refund/add`
- 说明：创建售后单

```jsonc
{
  "order_no": "ORDER_NO", // 原订单号
  "type": 1, // 售后类型
  "amount": "0.00", // 退款金额
  "reason": "尺寸不合适", // 售后原因
  "phone": "13800000000", // 联系手机号
  "content": "", // 可选，补充说明
  "images": "url1|url2" // 可选，凭证图片
}
```

### `/api/wemall/auth/refund/express`
- 说明：填写退货物流

```jsonc
{
  "code": "REFUND_CODE", // 售后单号
  "express_code": "yto", // 快递公司编码
  "express_no": "YT123456789" // 快递单号
}
```

### `/api/wemall/auth/refund/cancel`
- 说明：取消售后单

```jsonc
{
  "code": "REFUND_CODE" // 售后单号
}
```

### `/api/wemall/auth/refund/confirm`
- 说明：确认售后完成

```jsonc
{
  "code": "REFUND_CODE" // 售后单号
}
```

### `/api/wemall/auth/refund/reasons`
- 说明：获取售后原因列表

```jsonc
{}
```

### `/api/wemall/auth/spread/get`
- 说明：分页获取我推广的用户

```jsonc
{
  "page": 1 // 页码
}
```

### `/api/wemall/auth/spread/bind`
- 说明：临时绑定推荐人

```jsonc
{
  "from": 1 // 推荐人用户 ID
}
```

### `/api/wemall/auth/spread/poster`
- 说明：获取推广海报

```jsonc
{}
```

### `/api/wemall/auth/transfer/add`
- 说明：提交提现申请

```jsonc
{
  "type": "alipay_account", // 提现方式
  "amount": "100.00", // 提现金额
  "remark": "用户提交提现申请！", // 可选，提现备注
  "alipay_user": "", // 支付宝开户姓名
  "alipay_code": "", // 支付宝收款账号
  "qrcode": "", // 二维码收款图
  "bank_wseq": "", // 银行联行号
  "bank_name": "", // 开户银行名称
  "bank_user": "", // 开户人姓名
  "bank_bran": "", // 开户支行
  "bank_code": "" // 银行卡号
}
```

### `/api/wemall/auth/transfer/get`
- 说明：分页获取提现记录

```jsonc
{
  "status": "", // 可选，提现状态
  "keys": "", // 可选，日期或单号关键字
  "page": 1 // 页码
}
```

### `/api/wemall/auth/transfer/cancel`
- 说明：取消提现申请

```jsonc
{
  "code": "TRANSFER_CODE" // 提现单号
}
```

### `/api/wemall/auth/transfer/confirm`
- 说明：确认提现到账

```jsonc
{
  "code": "TRANSFER_CODE" // 提现单号
}
```

### `/api/wemall/auth/transfer/config`
- 说明：获取提现配置

```jsonc
{}
```

### `/api/wemall/auth/action/collect/set`
- 说明：收藏商品

```jsonc
{
  "gcode": "G001" // 商品编码
}
```

### `/api/wemall/auth/action/collect/get`
- 说明：获取收藏列表

```jsonc
{
  "page": 1, // 页码
  "limit": 10 // 分页条数
}
```

### `/api/wemall/auth/action/collect/del`
- 说明：取消收藏

```jsonc
{
  "gcode": "G001" // 商品编码
}
```

### `/api/wemall/auth/action/collect/clear`
- 说明：清空收藏列表

```jsonc
{}
```

### `/api/wemall/auth/action/search/set`
- 说明：记录搜索关键字

```jsonc
{
  "keys": "羽绒服" // 搜索关键字
}
```

### `/api/wemall/auth/action/search/get`
- 说明：获取搜索记录

```jsonc
{
  "page": 1, // 页码
  "limit": 10 // 分页条数
}
```

### `/api/wemall/auth/action/history/set`
- 说明：记录商品浏览历史

```jsonc
{
  "gcode": "G001" // 商品编码
}
```

### `/api/wemall/auth/action/history/get`
- 说明：获取浏览历史

```jsonc
{
  "page": 1, // 页码
  "limit": 10 // 分页条数
}
```

### `/api/wemall/auth/action/history/del`
- 说明：删除单条浏览历史

```jsonc
{
  "gcode": "G001" // 商品编码
}
```

### `/api/wemall/auth/action/history/clear`
- 说明：清空浏览历史

```jsonc
{}
```