ShopOrder API 文档

概述

商家订单系统 API，提供订单创建、订单查询等功能。支持微信支付、支付宝支付和银联支付三种支付方式。

基础路径: /api/shop_order
认证方式: Bearer Token
数据格式: JSON

接口列表

认证方式

所有接口都需要通过 ApiMiddleware 中间件进行认证。

支持的认证方式：

Header 方式（推荐）:
```
Authorization: Bearer <your-token>
```

Query 参数方式:

GET /api/shop_order/info?order_sn=xxx&token=your-token

1. 获取订单详情

基本信息

接口路径: /api/shop_order/info
请求方式: GET
接口描述: 根据订单编号查询订单详细信息（包含店铺名称）
认证要求: 需要 Token 认证
请求头要求:
- Content-Type: application/json
- Authorization: Bearer {token}

请求参数

参数名	类型	位置	必填	说明	验证规则
order_sn	string	query	是	订单编号	required, min=1, max=64

请求示例

GET /api/shop_order/info?order_sn=382FS1234567890 HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here

响应格式

成功响应 (200)

{
    "code": 200,
    "message": "success",
    "data": {
        "rs_sn": "382FS1234567890",
        "pay_sn": "PAY20260312001",
        "status": 2,
        "pay_money": "100.00",
        "shop_name": "某某店铺"
    }
}

失败响应 - 参数错误 (400)

{
    "code": 400,
    "message": "订单编号不能为空",
    "data": []
}

失败响应 - 订单不存在 (400)

{
    "code": 400,
    "message": "订单不存在",
    "data": []
}

失败响应 - 认证失败 (401)

{
    "code": 401,
    "message": "token 失效",
    "data": null
}

返回字段说明

字段名	类型	说明
rs_sn	string	店铺订单支付编号
pay_sn	string	支付编号
status	int	订单状态（1：待支付，2：已支付，3：已退款/已完成）
pay_money	decimal	支付金额
shop_name	string	店铺名称

cURL 测试示例

# 正常查询
curl -X GET "http://localhost:8080/api/shop_order/info?order_sn=382FS1234567890" \
  -H "Authorization: Bearer your-token"

# 缺少参数测试
curl -X GET "http://localhost:8080/api/shop_order/info"

# 订单不存在测试
curl -X GET "http://localhost:8080/api/shop_order/info?order_sn=INVALID_SN"

注意事项

该接口需要登录认证（通过 ApiMiddleware）
订单编号必须是有效的字符串，长度不超过 64 个字符
如果订单不存在，会返回"订单不存在"的错误提示
接口会自动关联店铺表，返回店铺名称信息

2. 创建订单支付

基本信息

接口路径: /api/shop_order/create
请求方式: GET/POST
接口描述: 创建订单并获取支付信息（支持微信、支付宝、银联）
认证要求: ⚠️ 必须登录（微信支付时需要验证用户身份）
请求头要求:
- Content-Type: application/json
- Authorization: Bearer {token}（微信支付时必须）

请求参数

参数名	类型	位置	必填	说明	验证规则
shop_id	int	body/query	是	商家 ID	required, gt=0
pay_type	int	body/query	是	支付方式（1：微信，2：支付宝）	required, gt=0, lt=3
pay_money	string	body/query	是	支付金额	required, gt=0, lte=1000000
pay_code_source	int	body/query	否	收款码来源（1：普通，2：烟草）	omitempty

参数说明：

shop_id: 商家店铺 ID，必须大于 0
pay_type: 支付方式，1=微信支付，2=支付宝支付
pay_money: 支付金额，支持小数，最大 1000000
pay_code_source: 可选参数，默认为 1

请求示例

POST /api/shop_order/create HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here

{
    "shop_id": 1,
    "pay_type": 1,
    "pay_money": "100.00",
    "pay_code_source": 1
}

响应格式

成功响应 (200)

{
    "code": 200,
    "message": "success",
    "data": {
        "is_bank": 0,
        "wx_pay": {
            "appId": "wx1234567890",
            "timeStamp": "1234567890",
            "nonceStr": "random_string",
            "package": "prepay_id=xxx",
            "signType": "RSA",
            "paySign": "signature"
        },
        "zfb_pay": "",
        "pay_url": ""
    }
}

失败响应 - 参数错误 (400)

{
    "code": 400,
    "message": "商家 id 不能为空",
    "data": []
}

失败响应 - 金额错误 (400)

{
    "code": 400,
    "message": "金额不合法",
    "data": []
}

失败响应 - 会员信息错误 (409)

{
    "code": 409,
    "message": "会员信息错误",
    "data": []
}

失败响应 - 商户号信息错误 (400)

{
    "code": 400,
    "message": "商户号信息错误 xxx",
    "data": []
}

失败响应 - 订单创建失败 (400)

{
    "code": 400,
    "message": "订单创建失败",
    "data": []
}

返回字段说明

字段名	类型	说明
is_bank	int	是否银联支付（0：否，1：是）
wx_pay	object	微信支付参数（仅微信支付时返回）
zfb_pay	string	支付宝支付 URL（仅支付宝支付时返回）
pay_url	string	H5 支付跳转 URL（仅银联支付时返回）

wx_pay 对象结构（微信支付时返回）：

{
    "appId": "wx1234567890",
    "timeStamp": "1234567890",
    "nonceStr": "random_string",
    "package": "prepay_id=xxx",
    "signType": "RSA",
    "paySign": "signature"
}

cURL 测试示例

# 创建微信订单
curl -X POST "http://localhost:8080/api/shop_order/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "shop_id": 1,
    "pay_type": 1,
    "pay_money": "100.00"
  }'

# 创建支付宝订单
curl -X POST "http://localhost:8080/api/shop_order/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "shop_id": 1,
    "pay_type": 2,
    "pay_money": "50.00"
  }'

注意事项

当 pay_type=1（微信支付）时，必须携带有效的 token 以获取用户 openid
支付金额最小为 0.01 元，最大为 1000000 元
如果商户配置了银联信息，会走银联支付通道（is_bank=1）
微信支付返回前端 SDK 需要的支付参数，支付宝返回支付 URL，银联支付返回 H5 跳转链接
订单编号由系统自动生成，格式如：382FS + 时间戳

3. 获取商户银联待入账金额列表

基本信息

接口路径: /api/shop_order/bank_total
请求方式: GET
接口描述: 获取商户银联待入账订单列表（最新 10 条）及待入账总金额（已扣除清分金额）
认证要求: 需要 Token 认证
请求头要求:
- Content-Type: application/json
- Authorization: Bearer {token}

请求参数

无需参数，自动从 token 中获取会员信息并查询关联店铺。

请求示例

GET /api/shop_order/bank_total HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here

响应格式

成功响应 (200)

{
    "code": 200,
    "message": "success",
    "data": {
        "total_money": "19600.00",
        "list": [
            {
                "rs_sn": "382FS1234567890",
                "pay_money": "98.00",
                "is_clearing": 0,
                "status": 6,
                "created_at": "2026-03-14T10:00:00Z"
            },
            {
                "rs_sn": "382FS1234567891",
                "pay_money": "196.00",
                "is_clearing": 0,
                "status": 6,
                "created_at": "2026-03-14T09:00:00Z"
            }
        ]
    }
}

失败响应 - 未授权 (401)

{
    "code": 401,
    "message": "缺少登陆信息",
    "data": []
}

失败响应 - 未找到店铺 (400)

{
    "code": 400,
    "message": "未找到店铺信息",
    "data": []
}

返回字段说明

字段名	类型	说明
total_money	string	银联待入账总金额（已扣除清分金额）
list	array	订单列表（最新 10 条）

list 数组元素结构：

字段名	类型	说明
rs_sn	string	订单编号
pay_money	string	支付金额（已扣除清分金额）
is_clearing	int	是否清分（0：待清分，1：已清分）
status	int	订单状态（6：待入账）
created_at	string	创建时间（RFC3339 格式）

cURL 测试示例

# 查询最新 10 条银联待入账订单
curl -X GET "http://localhost:8080/api/shop_order/bank_total" \
  -H "Authorization: Bearer your-token"

注意事项

该接口需要登录认证，自动从 token 中获取会员 ID
根据会员 ID 自动查询其关联的店铺（未删除且状态为 1）
仅查询 status=6（待入账）且 is_bank=1（银联支付）的订单
固定返回最新的 10 条记录，按 ID 降序排序
返回的金额为扣除清分金额后的实际收益金额
清分比例由商户配置的 discount 字段决定（折扣百分比）
计算公式：待入账金额 = 总金额 - (总金额 × discount / 100)

4. 获取商户银联待入账金额列表 (带日期和分页)

基本信息

接口路径: /api/shop_order/bank_list
请求方式: GET
接口描述: 获取指定月份的商户银联待入账订单列表（支持分页）及统计信息
认证要求: 需要 Token 认证
请求头要求:
- Content-Type: application/json
- Authorization: Bearer {token}

请求参数

参数名	类型	位置	必填	说明	验证规则
date	string	query	否	查询月份，格式：Y-m，默认本月	datetime=2006-01
page	int	query	否	页码，默认 1	gt=0
page_size	int	query	否	每页数量，默认 10，最大 100	gt=0, lte=100

请求示例

GET /api/shop_order/bank_list?date=2026-03&page=1&page_size=10 HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Authorization: Bearer your-token-here

响应格式

成功响应 (200)

{
    "code": 200,
    "message": "success",
    "data": {
        "total": 50,
        "items": [
            {
                "rs_sn": "382FS1234567890",
                "pay_money": "98.00",
                "is_clearing": 0,
                "status": 6,
                "created_at": "2026-03-14T10:00:00Z"
            },
            {
                "rs_sn": "382FS1234567891",
                "pay_money": "196.00",
                "is_clearing": 0,
                "status": 4,
                "created_at": "2026-03-13T09:00:00Z"
            }
        ],
        "limit": 10,
        "end_date": "2026-04"
    }
}

失败响应 - 未授权 (401)

{
    "code": 401,
    "message": "缺少登陆信息",
    "data": []
}

失败响应 - 参数错误 (400)

{
    "code": 400,
    "message": "日期格式不正确",
    "data": []
}

返回字段说明

字段名	类型	说明
total	int	订单总数
items	array	订单列表（已扣除清分金额）
limit	int	每页数量
end_date	string	查询的月份（用户选择的日期或默认当前月）

items 数组元素结构：

字段名	类型	说明
rs_sn	string	订单编号
pay_money	string	支付金额（已扣除清分金额）
is_clearing	int	是否清分（0：待清分，1：已清分）
status	int	订单状态（4：已支付，6：待入账）
created_at	string	创建时间（RFC3339 格式）

cURL 测试示例

# 查询本月数据
curl -X GET "http://localhost:8080/api/shop_order/bank_list" \
  -H "Authorization: Bearer your-token"

# 查询指定月份
curl -X GET "http://localhost:8080/api/shop_order/bank_list?date=2026-03" \
  -H "Authorization: Bearer your-token"

# 自定义分页
curl -X GET "http://localhost:8080/api/shop_order/bank_list?date=2026-03&page=2&page_size=20" \
  -H "Authorization: Bearer your-token"

注意事项

该接口需要登录认证，自动从 token 中获取会员 ID
根据会员 ID 自动查询其关联的店铺（未删除且状态为 1）
仅查询 is_bank=1（银联支付）且 status 为 4 或 6 的订单
日期参数格式为 Y-m（如：2026-03），默认为当前月份
查询范围为指定月份的 1 号至月底
返回的金额为扣除清分金额后的实际收益金额
清分比例由商户配置的 discount 字段决定（折扣百分比）
分页参数有默认值，page 默认 1，page_size 默认 10，最大 100
end_date 返回的是用户选择的月份，未选择则返回当前月份

通用说明

错误码说明

错误码	HTTP 状态码	说明	常见场景
200	200 OK	成功	请求成功处理
400	Bad Request	请求参数错误	参数缺失、格式错误、验证失败
401	Unauthorized	未授权/认证失败	token 无效、过期或缺失
409	Conflict	资源冲突	会员信息错误、数据不存在

业务错误信息详见各接口的响应格式说明。

数据格式

请求/响应格式： JSON (application/json)

金额精度：

使用 decimal.Decimal 类型，保留两位小数
支持字符串或数字传递

时间格式： RFC3339 格式（created_at、updated_at）

版本信息

API 版本: v1
最后更新: 2026-03-14
维护者: 开发团队
文档路径: /doc/shopOrder.md

更新日志

v1.2.0 (2026-03-14)

✨ 新增：获取商户银联待入账金额列表接口 /bank_list（带日期和分页）
📝 说明：原 /bank_total 接口保留，作为快速查询接口

v1.1.0 (2026-03-14)

✨ 新增：获取商户银联待入账金额列表接口 /bank_total
🐛 修复：优化订单查询逻辑，移除分页参数
🔧 改进：简化响应数据结构，提升查询性能
📝 重构：方法名从 GetBankOrderList 改为 GetShopBankOrder

v1.0.0 (2026-03-13)

✨ 新增：获取订单详情接口 /info
🐛 修复：优化订单查询接口的参数验证
📝 改进：完善 API 文档说明

v1.0.0 (2026-03-12)

✨ 初始版本：创建订单支付接口 /create

shopOrder.md 15 KB تاريخچه خام

ShopOrder API 文档

概述

目录

接口列表

认证方式

1. 获取订单详情

基本信息

请求参数

请求示例

响应格式

返回字段说明

cURL 测试示例

注意事项

2. 创建订单支付

基本信息

请求参数

请求示例

响应格式

返回字段说明

cURL 测试示例

注意事项

3. 获取商户银联待入账金额列表

基本信息

请求参数

请求示例

响应格式

返回字段说明

cURL 测试示例

注意事项

4. 获取商户银联待入账金额列表 (带日期和分页)

基本信息

请求参数

请求示例

响应格式

返回字段说明

cURL 测试示例

注意事项

通用说明

错误码说明

数据格式

版本信息

更新日志

v1.2.0 (2026-03-14)

v1.1.0 (2026-03-14)

v1.0.0 (2026-03-13)

v1.0.0 (2026-03-12)

shopOrder.md 15 KB

تاريخچه خام