# ShopOrder API 文档 ## 概述 商家订单系统 API，提供订单创建、订单查询等功能。支持微信支付、支付宝支付和银联支付三种支付方式。 **基础路径**: `/api/shopOrder` **认证方式**: Bearer Token **数据格式**: JSON --- ## 目录 - [获取订单详情](#获取订单详情) - [创建订单支付](#创建订单支付) - [获取商户银联待入账金额列表](#获取商户银联待入账金额列表) --- ## 接口列表 ### 认证方式 所有接口都需要通过 `ApiMiddleware` 中间件进行认证。 **支持的认证方式：** 1. **Header 方式**（推荐）: ``` Authorization: Bearer ``` 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`