|
@@ -0,0 +1,455 @@
|
|
|
|
|
+# ShopOrder API 文档
|
|
|
|
|
+
|
|
|
|
|
+## 概述
|
|
|
|
|
+
|
|
|
|
|
+商家订单系统 API,提供订单创建、订单查询等功能。支持微信支付、支付宝支付和银联支付三种支付方式。
|
|
|
|
|
+
|
|
|
|
|
+**基础路径**: `/api/shopOrder`
|
|
|
|
|
+**认证方式**: Bearer Token
|
|
|
|
|
+**数据格式**: JSON
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 目录
|
|
|
|
|
+
|
|
|
|
|
+- [获取订单详情](#获取订单详情)
|
|
|
|
|
+- [创建订单支付](#创建订单支付)
|
|
|
|
|
+- [获取商户银联待入账金额列表](#获取商户银联待入账金额列表)
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+## 接口列表
|
|
|
|
|
+
|
|
|
|
|
+### 认证方式
|
|
|
|
|
+
|
|
|
|
|
+所有接口都需要通过 `ApiMiddleware` 中间件进行认证。
|
|
|
|
|
+
|
|
|
|
|
+**支持的认证方式:**
|
|
|
|
|
+
|
|
|
|
|
+1. **Header 方式**(推荐):
|
|
|
|
|
+ ```
|
|
|
|
|
+ Authorization: Bearer <your-token>
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+2. **Query 参数方式**:
|
|
|
|
|
+ ```
|
|
|
|
|
+ GET /api/shopOrder/info?order_sn=xxx&token=your-token
|
|
|
|
|
+ ```
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 1. 获取订单详情
|
|
|
|
|
+
|
|
|
|
|
+#### 基本信息
|
|
|
|
|
+- **接口路径**: `/api/shopOrder/info`
|
|
|
|
|
+- **请求方式**: GET
|
|
|
|
|
+- **接口描述**: 根据订单编号查询订单详细信息(包含店铺名称)
|
|
|
|
|
+- **认证要求**: 需要 Token 认证
|
|
|
|
|
+- **请求头要求**:
|
|
|
|
|
+ - `Content-Type`: application/json
|
|
|
|
|
+ - `Authorization`: Bearer {token}
|
|
|
|
|
+
|
|
|
|
|
+#### 请求参数
|
|
|
|
|
+
|
|
|
|
|
+| 参数名 | 类型 | 位置 | 必填 | 说明 | 验证规则 |
|
|
|
|
|
+|--------|------|------|------|------|----------|
|
|
|
|
|
+| order_sn | string | query | 是 | 订单编号 | required, min=1, max=64 |
|
|
|
|
|
+
|
|
|
|
|
+#### 请求示例
|
|
|
|
|
+
|
|
|
|
|
+```http
|
|
|
|
|
+GET /api/shopOrder/info?order_sn=382FS1234567890 HTTP/1.1
|
|
|
|
|
+Host: localhost:8080
|
|
|
|
|
+Content-Type: application/json
|
|
|
|
|
+Authorization: Bearer your-token-here
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 响应格式
|
|
|
|
|
+
|
|
|
|
|
+**成功响应 (200)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 200,
|
|
|
|
|
+ "message": "success",
|
|
|
|
|
+ "data": {
|
|
|
|
|
+ "rs_sn": "382FS1234567890",
|
|
|
|
|
+ "pay_sn": "PAY20260312001",
|
|
|
|
|
+ "status": 2,
|
|
|
|
|
+ "pay_money": "100.00",
|
|
|
|
|
+ "shop_name": "某某店铺"
|
|
|
|
|
+ }
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 参数错误 (400)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 400,
|
|
|
|
|
+ "message": "订单编号不能为空",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 订单不存在 (400)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 400,
|
|
|
|
|
+ "message": "订单不存在",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 认证失败 (401)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 401,
|
|
|
|
|
+ "message": "token 失效",
|
|
|
|
|
+ "data": null
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 返回字段说明
|
|
|
|
|
+
|
|
|
|
|
+| 字段名 | 类型 | 说明 |
|
|
|
|
|
+|--------|------|------|
|
|
|
|
|
+| rs_sn | string | 店铺订单支付编号 |
|
|
|
|
|
+| pay_sn | string | 支付编号 |
|
|
|
|
|
+| status | int | 订单状态(1:待支付,2:已支付,3:已退款/已完成) |
|
|
|
|
|
+| pay_money | decimal | 支付金额 |
|
|
|
|
|
+| shop_name | string | 店铺名称 |
|
|
|
|
|
+
|
|
|
|
|
+#### cURL 测试示例
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+# 正常查询
|
|
|
|
|
+curl -X GET "http://localhost:8080/api/shopOrder/info?order_sn=382FS1234567890" \
|
|
|
|
|
+ -H "Authorization: Bearer your-token"
|
|
|
|
|
+
|
|
|
|
|
+# 缺少参数测试
|
|
|
|
|
+curl -X GET "http://localhost:8080/api/shopOrder/info"
|
|
|
|
|
+
|
|
|
|
|
+# 订单不存在测试
|
|
|
|
|
+curl -X GET "http://localhost:8080/api/shopOrder/info?order_sn=INVALID_SN"
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 注意事项
|
|
|
|
|
+
|
|
|
|
|
+1. 该接口需要登录认证(通过 `ApiMiddleware`)
|
|
|
|
|
+2. 订单编号必须是有效的字符串,长度不超过 64 个字符
|
|
|
|
|
+3. 如果订单不存在,会返回"订单不存在"的错误提示
|
|
|
|
|
+4. 接口会自动关联店铺表,返回店铺名称信息
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 2. 创建订单支付
|
|
|
|
|
+
|
|
|
|
|
+#### 基本信息
|
|
|
|
|
+- **接口路径**: `/api/shopOrder/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
|
|
|
|
|
+
|
|
|
|
|
+#### 请求示例
|
|
|
|
|
+
|
|
|
|
|
+```http
|
|
|
|
|
+POST /api/shopOrder/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)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "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)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 400,
|
|
|
|
|
+ "message": "商家 id 不能为空",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 金额错误 (400)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 400,
|
|
|
|
|
+ "message": "金额不合法",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 会员信息错误 (409)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 409,
|
|
|
|
|
+ "message": "会员信息错误",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 商户号信息错误 (400)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 400,
|
|
|
|
|
+ "message": "商户号信息错误 xxx",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 订单创建失败 (400)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 400,
|
|
|
|
|
+ "message": "订单创建失败",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 返回字段说明
|
|
|
|
|
+
|
|
|
|
|
+| 字段名 | 类型 | 说明 |
|
|
|
|
|
+|--------|------|------|
|
|
|
|
|
+| is_bank | int | 是否银联支付(0:否,1:是) |
|
|
|
|
|
+| wx_pay | object | 微信支付参数(仅微信支付时返回) |
|
|
|
|
|
+| zfb_pay | string | 支付宝支付 URL(仅支付宝支付时返回) |
|
|
|
|
|
+| pay_url | string | H5 支付跳转 URL(仅银联支付时返回) |
|
|
|
|
|
+
|
|
|
|
|
+**wx_pay 对象结构(微信支付时返回):**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "appId": "wx1234567890",
|
|
|
|
|
+ "timeStamp": "1234567890",
|
|
|
|
|
+ "nonceStr": "random_string",
|
|
|
|
|
+ "package": "prepay_id=xxx",
|
|
|
|
|
+ "signType": "RSA",
|
|
|
|
|
+ "paySign": "signature"
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### cURL 测试示例
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+# 创建微信订单
|
|
|
|
|
+curl -X POST "http://localhost:8080/api/shopOrder/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/shopOrder/create" \
|
|
|
|
|
+ -H "Content-Type: application/json" \
|
|
|
|
|
+ -H "Authorization: Bearer your-token" \
|
|
|
|
|
+ -d '{
|
|
|
|
|
+ "shop_id": 1,
|
|
|
|
|
+ "pay_type": 2,
|
|
|
|
|
+ "pay_money": "50.00"
|
|
|
|
|
+ }'
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 注意事项
|
|
|
|
|
+
|
|
|
|
|
+1. 当 `pay_type=1`(微信支付)时,必须携带有效的 token 以获取用户 openid
|
|
|
|
|
+2. 支付金额最小为 0.01 元,最大为 1000000 元
|
|
|
|
|
+3. 如果商户配置了银联信息,会走银联支付通道(`is_bank=1`)
|
|
|
|
|
+4. 微信支付返回前端 SDK 需要的支付参数,支付宝返回支付 URL,银联支付返回 H5 跳转链接
|
|
|
|
|
+5. 订单编号由系统自动生成,格式如:382FS + 时间戳
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 3. 获取商户银联待入账金额列表
|
|
|
|
|
+
|
|
|
|
|
+#### 基本信息
|
|
|
|
|
+- **接口路径**: `/api/shopOrder/shopBankOrder`
|
|
|
|
|
+- **请求方式**: GET
|
|
|
|
|
+- **接口描述**: 获取商户银联待入账订单列表(最新 10 条)及待入账总金额(已扣除清分金额)
|
|
|
|
|
+- **认证要求**: 需要 Token 认证
|
|
|
|
|
+- **请求头要求**:
|
|
|
|
|
+ - `Content-Type`: application/json
|
|
|
|
|
+ - `Authorization`: Bearer {token}
|
|
|
|
|
+
|
|
|
|
|
+#### 请求参数
|
|
|
|
|
+
|
|
|
|
|
+无需参数,自动从 token 中获取会员信息并查询关联店铺。
|
|
|
|
|
+
|
|
|
|
|
+#### 请求示例
|
|
|
|
|
+
|
|
|
|
|
+```http
|
|
|
|
|
+GET /api/shopOrder/shopBankOrder HTTP/1.1
|
|
|
|
|
+Host: localhost:8080
|
|
|
|
|
+Content-Type: application/json
|
|
|
|
|
+Authorization: Bearer your-token-here
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 响应格式
|
|
|
|
|
+
|
|
|
|
|
+**成功响应 (200)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "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)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "code": 401,
|
|
|
|
|
+ "message": "缺少登陆信息",
|
|
|
|
|
+ "data": []
|
|
|
|
|
+}
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+**失败响应 - 未找到店铺 (400)**
|
|
|
|
|
+```json
|
|
|
|
|
+{
|
|
|
|
|
+ "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 测试示例
|
|
|
|
|
+
|
|
|
|
|
+```bash
|
|
|
|
|
+# 查询最新 10 条银联待入账订单
|
|
|
|
|
+curl -X GET "http://localhost:8080/api/shopOrder/shopBankOrder" \
|
|
|
|
|
+ -H "Authorization: Bearer your-token"
|
|
|
|
|
+```
|
|
|
|
|
+
|
|
|
|
|
+#### 注意事项
|
|
|
|
|
+
|
|
|
|
|
+1. 该接口需要登录认证,自动从 token 中获取会员 ID
|
|
|
|
|
+2. 根据会员 ID 自动查询其关联的店铺(未删除且状态为 1)
|
|
|
|
|
+3. 仅查询 status=6(待入账)且 is_bank=1(银联支付)的订单
|
|
|
|
|
+4. 固定返回最新的 10 条记录,按 ID 降序排序
|
|
|
|
|
+5. 返回的金额为扣除清分金额后的实际收益金额
|
|
|
|
|
+6. 清分比例由商户配置的 discount 字段决定(折扣百分比)
|
|
|
|
|
+7. 计算公式:`待入账金额 = 总金额 - (总金额 × discount / 100)`
|
|
|
|
|
+
|
|
|
|
|
+---
|
|
|
|
|
+
|
|
|
|
|
+### 通用说明
|
|
|
|
|
+
|
|
|
|
|
+### 错误码说明
|
|
|
|
|
+
|
|
|
|
|
+| 错误码 | 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.0.0 (2026-03-13)
|
|
|
|
|
+- ✨ 新增:获取订单详情接口 `/info`
|
|
|
|
|
+- 🐛 修复:优化订单查询接口的参数验证
|
|
|
|
|
+- 📝 改进:完善 API 文档说明
|
|
|
|
|
+
|
|
|
|
|
+#### v1.0.0 (2026-03-12)
|
|
|
|
|
+- ✨ 初始版本:创建订单支付接口 `/create`
|