scottpan/integral-shop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6d3b50cebc664c267a6a184c67819ffd30fa1a4b
integral-shop/backend/docs/后端API接口文档.md

1061 lines
20 KiB
Markdown
Raw Normal View History

Initial commit: 单商户积分商城 - 管理后台前端 + CRMEB 后端 Made-with: Cursor
2026-03-08 18:35:11 +08:00
# H5商城网站API接口文档
> **API Base URL**: http://miao1admin.suzhouyuqi.com
> **分析时间**: 2025-11-08
> **接口协议**: HTTP/HTTPS
> **数据格式**: JSON
> **认证方式**: Bearer Token (Header: Authori-zation)
---
## 📋 文档说明
本文档基于服务器日志 `webman-2025-11-03.log` 和前端编译文件分析生成，记录了H5商城网站的所有API接口。
### 通用说明
- 所有需要登录的接口都需要在请求头中携带 Token
- Token 名称：`Authori-zation`
- 请求格式：`application/json` 或 `application/x-www-form-urlencoded`
- 响应格式：JSON
### 错误码说明
```json
{
"code": 0, // 0=成功，非0=失败
"msg": "提示信息",
"data": {} // 返回数据
}
```
---
## 目录
1. [用户认证接口](#一用户认证接口)
2. [商品相关接口](#二商品相关接口)
3. [订单相关接口](#三订单相关接口)
4. [地址管理接口](#四地址管理接口)
5. [财务相关接口](#五财务相关接口)
6. [支付相关接口](#六支付相关接口)
7. [分享推广接口](#七分享推广接口)
8. [首页相关接口](#八首页相关接口)
9. [短信相关接口](#九短信相关接口)
---
## 一、用户认证接口
### 1.1 用户登录
**接口地址**: `/api/user/login`
**请求方式**: `POST`
**是否需要登录**: 否
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| account | string | 是 | 手机号/账号 |
| password | string | 是 | 密码 |
**请求示例**:
```json
{
"account": "18379637515",
"password": "123456"
}
```
**返回示例**:
```json
{
"code": 0,
"msg": "登录成功",
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"user_info": {
"id": 92564,
"mobile": "18379637515",
"nickname": "用户昵称",
"avatar": "头像URL"
}
}
}
```
---
### 1.2 用户注册
**接口地址**: `/api/user/register`
**请求方式**: `POST`
**是否需要登录**: 否
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mobile | string | 是 | 手机号 |
| password | string | 是 | 密码 |
| code | string | 是 | 短信验证码 |
| invite_code | string | 否 | 邀请码 |
---
### 1.3 获取用户信息
**接口地址**: `/api/user/info`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 92564,
"mobile": "18379637515",
"nickname": "用户昵称",
"avatar": "头像URL",
"share_bonus": "1234.56", // 分红余额
"self_bonus": "789.12", // 自购分红
"coupon": "456.78", // 优惠券余额
"today_share_bonus": "123.45", // 今日分红
"total_share_bonus": "9876.54" // 累计分红
}
}
```
---
### 1.4 修改用户昵称
**接口地址**: `/api/user/nickname`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| nickname | string | 是 | 新昵称 |
---
### 1.5 修改密码
**接口地址**: `/api/user/changepwd`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| old_password | string | 是 | 原密码 |
| new_password | string | 是 | 新密码 |
| code | string | 是 | 短信验证码 |
---
## 二、商品相关接口
### 2.1 获取商品分类
**接口地址**: `/api/goods/category`
**请求方式**: `GET`
**是否需要登录**: 否
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 1,
"name": "分类名称"
}
]
}
```
---
### 2.2 获取商品列表
**接口地址**: `/api/goods/list`
**请求方式**: `GET`
**是否需要登录**: 否
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| cate_id | int | 是 | 分类ID |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 1,
"title": "商品标题",
"images": ["图片1", "图片2"],
"price": "199.00",
"line_price": "299.00",
"sales_volume": 1000
}
]
}
```
---
### 2.3 获取商品详情
**接口地址**: `/api/goods/detail`
**请求方式**: `GET`
**是否需要登录**: 否
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 商品ID |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 2,
"title": "商品标题",
"images": ["图片1", "图片2"],
"price": "199.00",
"line_price": "299.00",
"sales_volume": 1000,
"content": "商品详情",
"customer_service": "客服微信"
}
}
```
---
## 三、订单相关接口
### 3.1 订单首页数据
**接口地址**: `/api/order/index`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"shop_name": "商城名称",
"open_week": "1,2,3,4,5", // 开放星期
"start_time": "09:00", // 开始时间
"end_time": "21:00", // 结束时间
"goods_id": "1", // 商品ID
"goods_image": "商品图片",
"goods_setting": { // 商品配置
"max_buy": 3 // 最大购买数量
}
}
}
```
---
### 3.2 可购买商品列表
**接口地址**: `/api/order/goods`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 是 | 页码 |
| limit | int | 是 | 每页数量 |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"total": 100,
"list": [
{
"id": 144754,
"old_id": 149113,
"user_id": 92679,
"title": "鲜锋活力宝",
"image": "\/upload\/image\/20250914\/44d45afc28b6dfb47c20d127a7b64540_68c69ec7a6b0a.jpg",
"price": "29805.86",
"is_show": 1,
"status": 1,
"created_at": "2025-11-09 17:27:34",
"updated_at": "2025-11-09 13:25:48",
"total_money": "29805.86",
"seller_id": 92679,
"quantity": "≈3箱"
}
]
}
}
```
---
### 3.3 购买商品（抢单）
**接口地址**: `/api/order/buy`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 寄卖商品ID |
| seller_id | int | 是 | 卖家用户ID |
**请求示例**:
```json
{
"id": 143657,
"seller_id": 92467
}
```
---
### 3.4 订单列表
**接口地址**: `/api/order/list`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| cate | int | 是 | 分类：1=买方仓库，2=卖方仓库 |
| type | int | 是 | 类型：1=寄卖中/交易中，2=已完成 |
| page | int | 是 | 页码 |
| limit | int | 是 | 每页数量 |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"total": 50,
"list": [
{
"id": 148674,
"order_sn": "订单号",
"merchandise_id": 143657,
"merchandise_title": "商品标题",
"merchandise_image": "商品图片",
"total_money": "199.00",
"status": 1, // 0=待支付，1=已支付，2=已完成
"buyer_nickname": "买家昵称",
"seller_nickname": "卖家昵称",
"created_at": "2025-11-03 09:00:00",
"pay_time": "2025-11-03 09:01:00",
"confirm_time": "2025-11-03 09:10:00"
}
]
}
}
```
---
### 3.5 订单详情
**接口地址**: `/api/order/detail`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| order_id | int | 是 | 订单ID |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 148674,
"order_sn": "订单号",
"merchandise_title": "商品标题",
"merchandise_image": "商品图片",
"total_money": "199.00",
"status": 1,
"buyer_nickname": "买家昵称",
"seller_nickname": "卖家昵称",
"consignee": "收货人",
"phone": "手机号",
"province": "省",
"city": "市",
"area": "区",
"address": "详细地址"
}
}
```
---
### 3.6 支付订单
**接口地址**: `/api/order/pay`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| order_id | int | 是 | 订单ID |
| address_id | int | 是 | 收货地址ID |
**请求示例**:
```json
{
"order_id": 148674,
"address_id": 2911
}
```
---
### 3.7 确认订单（卖家发货）
**接口地址**: `/api/order/confirm`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| order_id | int | 是 | 订单ID |
**请求示例**:
```json
{
"order_id": 148674
}
```
---
### 3.8 取消订单
**接口地址**: `/api/order/cancel`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| order_id | int | 是 | 订单ID |
---
### 3.9 转卖订单
**接口地址**: `/api/order/resell`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| order_id | int | 是 | 订单ID |
---
## 四、地址管理接口
### 4.1 地址列表
**接口地址**: `/api/address/list`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 2911,
"consignee": "收货人",
"phone": "13584195313",
"province": "江苏省",
"city": "无锡市",
"area": "锡山区",
"address": "中大诺卡小镇",
"is_default": 1
}
]
}
```
---
### 4.2 获取默认地址
**接口地址**: `/api/address/default`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 2911,
"consignee": "收货人",
"phone": "13584195313",
"province": "江苏省",
"city": "无锡市",
"area": "锡山区",
"address": "中大诺卡小镇",
"is_default": 1
}
}
```
---
### 4.3 新增地址
**接口地址**: `/api/address/insert`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| consignee | string | 是 | 收货人 |
| phone | string | 是 | 手机号 |
| province | string | 是 | 省 |
| city | string | 是 | 市 |
| area | string | 是 | 区 |
| address | string | 是 | 详细地址 |
| is_default | int | 否 | 是否默认：0=否，1=是 |
---
### 4.4 更新地址
**接口地址**: `/api/address/update`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 地址ID |
| consignee | string | 是 | 收货人 |
| phone | string | 是 | 手机号 |
| province | string | 是 | 省 |
| city | string | 是 | 市 |
| area | string | 是 | 区 |
| address | string | 是 | 详细地址 |
| is_default | int | 否 | 是否默认：0=否，1=是 |
---
### 4.5 删除地址
**接口地址**: `/api/address/delete`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | int | 是 | 地址ID |
---
## 五、财务相关接口
### 5.1 财务记录列表
**接口地址**: `/api/money/list`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| cate | int | 是 | 分类：1=分红明细，2=优惠券明细，3=自购分红明细 |
| type | int | 是 | 类型：1=收入，2=支出 |
| page | int | 是 | 页码 |
| limit | int | 是 | 每页数量 |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"total": 100,
"list": [
{
"id": 1234,
"type": 1, // 1=收入，2=支出
"money": "123.45",
"before": "1000.00", // 变动前余额
"after": "1123.45", // 变动后余额
"memo": "今日收益",
"created_at": "2025-11-03 09:00:00"
}
]
}
}
```
---
### 5.2 提现记录
**接口地址**: `/api/money/log`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 是 | 页码 |
| limit | int | 是 | 每页数量 |
---
### 5.3 申请提现
**接口地址**: `/api/money/withdraw`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | int | 是 | 提现类型：1=分红，2=优惠券 |
| money | string | 是 | 提现金额 |
---
## 六、支付相关接口
### 6.1 获取支付宝信息
**接口地址**: `/api/alipay/index`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 123,
"alipay_account": "支付宝账号",
"alipay_name": "支付宝姓名"
}
}
```
---
### 6.2 绑定支付宝
**接口地址**: `/api/alipay/bind`
**请求方式**: `POST`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| alipay_account | string | 是 | 支付宝账号 |
| alipay_name | string | 是 | 支付宝姓名 |
---
### 6.3 获取银行卡信息
**接口地址**: `/api/bank/index`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"id": 123,
"bank_name": "银行名称",
"bank_account": "银行卡号",
"account_name": "持卡人姓名"
}
}
```
---
## 七、分享推广接口
### 7.1 分享首页数据
**接口地址**: `/api/share/index`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"invite_code": "ABC123", // 邀请码
"direct_count": 10, // 直推人数
"team_count": 50, // 团队人数
"share_link": "https://..." // 分享链接
}
}
```
---
### 7.2 我的粉丝列表
**接口地址**: `/api/share/select`
**请求方式**: `GET`
**是否需要登录**: 是
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 是 | 页码 |
| limit | int | 是 | 每页数量 |
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"total": 20,
"list": [
{
"id": 92490,
"avatar": "头像",
"nickname": "用户昵称",
"mobile": "138****1234",
"team_count": 5, // 下级团队人数
"created_at": "2025-11-03 09:00:00"
}
]
}
}
```
---
## 八、首页相关接口
### 8.1 轮播图
**接口地址**: `/api/index/banner`
**请求方式**: `GET`
**是否需要登录**: 否
**请求参数**: 无
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 1,
"image": "轮播图URL",
"url": "跳转链接"
}
]
}
```
---
### 8.2 首页配置数据
**接口地址**: `/api/index/get`
**请求方式**: `POST`
**是否需要登录**: 否
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| title | string | 是 | 配置标题，如"公告消息" |
**请求示例**:
```json
{
"title": "公告消息"
}
```
**返回示例**:
```json
{
"code": 0,
"msg": "success",
"data": {
"value": "公告内容"
}
}
```
---
## 九、短信相关接口
### 9.1 发送短信验证码
**接口地址**: `/api/sms/send`
**请求方式**: `POST`
**是否需要登录**: 否
**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| mobile | string | 是 | 手机号 |
| event | string | 是 | 事件类型：register=注册，resetpwd=重置密码，changepwd=修改密码 |
**请求示例**:
```json
{
"mobile": "13585643985",
"event": "resetpwd"
}
```
**返回示例**:
```json
{
"code": 0,
"msg": "短信发送成功"
}
```
---
## 十、其他接口
### 10.1 签名回调
**接口地址**: `/api/notify/sign`
**请求方式**: `POST`
**是否需要登录**: 否
**说明**: 第三方签名回调接口
---
## 📊 接口汇总表
| 模块 | 接口数量 | 说明 |
|------|---------|------|
| 用户认证 | 5 | 登录、注册、信息获取、修改 |
| 商品管理 | 3 | 分类、列表、详情 |
| 订单管理 | 9 | 下单、支付、发货、取消等 |
| 地址管理 | 5 | 增删改查、默认地址 |
| 财务管理 | 3 | 明细、提现 |
| 支付管理 | 3 | 支付宝、银行卡 |
| 分享推广 | 2 | 分享数据、粉丝列表 |
| 首页相关 | 2 | 轮播图、配置 |
| 短信服务 | 1 | 验证码发送 |
| **总计** | **33** | **全部接口** |
---
## 🔐 Token 说明
### 获取 Token
用户登录成功后，响应数据中会返回 `token` 字段。
### 使用 Token
在需要登录的接口请求头中携带：
```
Authori-zation: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```
**注意**: Header 名称是 `Authori-zation` (不是标准的 Authorization)
---
## ⚙️ 业务逻辑说明
### 订单状态流程
1. **待支付** (status=0): 买家抢单成功，但未支付
2. **已支付** (status=1): 买家已支付，等待卖家发货确认
3. **已完成** (status=2): 卖家确认发货，订单完成，开始分红
### 订单分类
- **买方仓库** (cate=1): 我购买的商品订单
- **卖方仓库** (cate=2): 我寄卖的商品订单
### 财务分类
- **分红余额** (share_bonus): 推广分红
- **自购分红** (self_bonus): 自购返利
- **优惠券** (coupon): 优惠券余额
### 短信事件类型
- `register`: 注册
- `resetpwd`: 重置密码
- `changepwd`: 修改密码
---
## 🧪 测试示例
### 登录测试
```bash
curl -X POST http://miao1admin.suzhouyuqi.com/api/user/login \
-H "Content-Type: application/json" \
-d '{
"account": "18379637515",
"password": "123456"
}'
```
### 获取用户信息
```bash
curl -X POST http://miao1admin.suzhouyuqi.com/api/user/info \
-H "Content-Type: application/json" \
-H "Authori-zation: Bearer YOUR_TOKEN"
```
### 获取商品列表
```bash
curl "http://miao1admin.suzhouyuqi.com/api/goods/list?cate_id=1"
```
### 订单列表（卖方仓库）
```bash
curl "http://miao1admin.suzhouyuqi.com/api/order/list?cate=2&type=1&page=1&limit=10" \
-H "Authori-zation: Bearer YOUR_TOKEN"
```
---
## 📝 注意事项
1. **认证头名称**: 注意是 `Authori-zation` 而非标准的 `Authorization`
2. **POST 方法**: 某些查询接口如 `/api/user/info`、`/api/order/index` 使用 POST 方法
3. **限流机制**: 部分接口有访问频率限制，使用 Redis 实现
4. **营业时间**: 商品购买受营业时间限制（通过 open_week、start_time、end_time 控制）
5. **防重复提交**: 关键操作（购买、支付、确认）有防重复提交机制
---
## 📅 更新日志
- **2025-11-08**: 基于 webman-2025-11-03.log 日志完整分析，新增 33 个接口文档
---
Reference in New Issue Copy Permalink