增加91卡券订单示例
This commit is contained in:
yml
@@ -0,0 +1,203 @@
|
||||
# 91卡券查询订单接口
|
||||
|
||||
## 1. 接口说明
|
||||
|
||||
本文档为当前项目对接 `91卡券` 的正式技术文档，用于提交客服审核。
|
||||
|
||||
本接口用于在异步卡密下单后，由 `91卡券` 主动查询订单状态与最终卡密内容。
|
||||
|
||||
当前项目的最终交付物不是传统卡号密码，而是：
|
||||
|
||||
- 我方系统生成的**领取链接**；
|
||||
- 该链接将作为最终卡密内容，通过 `cards` 字段返回给 `91卡券`；
|
||||
- `91卡券` 再使用自动发货能力，将该领取链接展示给买家。
|
||||
|
||||
## 2. 请求方向
|
||||
|
||||
- `91卡券平台 -> 接入方系统`
|
||||
|
||||
## 3. 请求 URL
|
||||
|
||||
请按以下地址配置：
|
||||
|
||||
```text
|
||||
POST https://221329.cc.cd/api/v1/open/91/orders/query
|
||||
```
|
||||
|
||||
## 4. 请求方式
|
||||
|
||||
- `POST`
|
||||
- `Content-Type: application/json;charset=utf-8`
|
||||
|
||||
## 5. 签名规则
|
||||
|
||||
签名规则采用 2.签名规则示例 中的约定：
|
||||
|
||||
- 除 `sign` 外，所有参数按字段名 ASCII 升序排序；
|
||||
- 使用 `key=value&key=value` 方式拼接；
|
||||
- 前后拼接商户密钥；
|
||||
- 取 `MD5`，输出 32 位大写字符串；
|
||||
- 空值参数参与签名。
|
||||
|
||||
## 6. 请求参数
|
||||
|
||||
| 参数名 | 必填 | 类型 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `orderNo` | 是 | string | 商家订单号。 |
|
||||
| `timestamp` | 是 | long | 10 位秒级 Unix 时间戳，用于请求时效校验。 |
|
||||
| `version` | 是 | string | 固定传 `1.0`。 |
|
||||
| `sign` | 是 | string | 签名。 |
|
||||
|
||||
## 7. 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"orderNo": "P91KS202605040001",
|
||||
"timestamp": 1777867260,
|
||||
"version": "1.0",
|
||||
"sign": "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
|
||||
}
|
||||
```
|
||||
|
||||
## 8. MD5 源串示例
|
||||
|
||||
假设：
|
||||
|
||||
- `userId = 1001`
|
||||
- 商户密钥为：`your_secret_key`
|
||||
|
||||
则源串示例如下：
|
||||
|
||||
```text
|
||||
your_secret_keyorderNo=P91KS202605040001×tamp=1777867260&userId=1001&version=1.0your_secret_key
|
||||
```
|
||||
|
||||
## 9. 业务处理规则
|
||||
|
||||
我方系统收到查询请求后，按以下规则返回：
|
||||
|
||||
1. 校验签名与时间戳；
|
||||
2. 根据 `orderNo` 查询内部订单；
|
||||
3. 若订单存在但领取链接尚未准备完成，返回 `orderStatus = 10`；
|
||||
4. 若领取链接已生成，可交付，返回 `orderStatus = 20`；
|
||||
5. 若订单无法履约，返回 `orderStatus = 30`；
|
||||
6. 当返回 `20` 时，通过 `cards` 返回最终卡密内容。
|
||||
|
||||
## 10. 响应参数
|
||||
|
||||
| 参数名 | 类型 | 必须返回 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `orderNo` | string | 必须返回 | 商家订单号，来源 `91卡券` 下单请求。 |
|
||||
| `outTradeNo` | string | 必须返回 | 我方系统内部订单号。 |
|
||||
| `orderStatus` | int | 必须返回 | 订单状态。`10`：处理中；`20`：成功；`30`：失败。 |
|
||||
| `failCode` | int | 失败时建议返回 | 失败代码。可以不返回该字段，但不要返回 `null`。 |
|
||||
| `failReason` | string | 失败时建议返回 | 失败原因。 |
|
||||
| `orderCost` | decimal(14,4) | 成功时建议返回 | 订单总成本，单位：元。 |
|
||||
| `cards` | string | `orderStatus = 20` 时必须 | 卡密数据加密串。当前项目通过该字段返回领取链接。 |
|
||||
| `cards[0].cardNo` | string | 成功时必须 | 最终交付的领取链接，格式为 `https://221329.cc.cd/#/claim/{token}`。 |
|
||||
| `cards[0].cardPwd` | string | 可选 | 当前场景固定为空字符串。 |
|
||||
| `cards[0].expireTime` | string | 可选 | 领取链接过期时间，支持 `yyyy-MM-dd HH:mm:ss` 或 10 位秒级 Unix 时间戳。 |
|
||||
| `cards[0].jumpLink` | string | 可选 | 与 `cardNo` 保持一致，用于兼容链接展示场景。 |
|
||||
|
||||
## 11. cards 原始结构约定
|
||||
|
||||
由于已确认允许将链接作为最终卡密内容展示给买家，当前项目约定：
|
||||
|
||||
- `cardNo`：直接放领取链接；
|
||||
- `cardPwd`：留空；
|
||||
- `expireTime`：放领取链接过期时间；
|
||||
- `jumpLink`：与 `cardNo` 一致。
|
||||
|
||||
原始结构示例如下：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"cardNo": "https://221329.cc.cd/#/claim/abc123xyz",
|
||||
"cardPwd": "",
|
||||
"expireTime": "2026-05-05 12:00:00",
|
||||
"jumpLink": "https://221329.cc.cd/#/claim/abc123xyz"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
若 `buyNum > 1`，则 `cards` 原始结构中返回多个卡项，每个卡项对应一个独立领取链接。
|
||||
|
||||
## 12. 响应示例
|
||||
|
||||
### 12.1 处理中
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "接口调用成功",
|
||||
"data": {
|
||||
"orderNo": "P91KS202605040001",
|
||||
"outTradeNo": "OS202605040001",
|
||||
"orderStatus": 10,
|
||||
"failCode": 0,
|
||||
"failReason": "",
|
||||
"orderCost": 0.0000,
|
||||
"cards": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 12.2 查询成功
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "接口调用成功",
|
||||
"data": {
|
||||
"orderNo": "P91KS202605040001",
|
||||
"outTradeNo": "OS202605040001",
|
||||
"orderStatus": 20,
|
||||
"failCode": 0,
|
||||
"failReason": "",
|
||||
"orderCost": 0.0000,
|
||||
"cards": "加密后的cards字符串"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`cards` 解密前原始结构示例：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"cardNo": "https://221329.cc.cd/#/claim/abc123xyz",
|
||||
"cardPwd": "",
|
||||
"expireTime": "2026-05-05 12:00:00",
|
||||
"jumpLink": "https://221329.cc.cd/#/claim/abc123xyz"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 12.3 查询失败
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "接口调用成功",
|
||||
"data": {
|
||||
"orderNo": "P91KS202605040001",
|
||||
"outTradeNo": "OS202605040001",
|
||||
"orderStatus": 30,
|
||||
"failCode": 1204,
|
||||
"failReason": "商品未配置或订单无法履约"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 13. 对接说明
|
||||
|
||||
- 本接口是 `91卡券` 自动发货的关键接口；
|
||||
- 当返回 `orderStatus = 20` 时，表示我方已准备好最终交付内容；
|
||||
- 最终交付内容是领取链接，不是传统卡号密码；
|
||||
- 领取链接域名固定为 `221329.cc.cd`；
|
||||
- 买家收到链接后，会进入我方系统领取页完成后续快手核销与履约流程；
|
||||
- 建议 `91卡券` 侧确认：
|
||||
- `cards.cardNo` 可直接展示完整链接；
|
||||
- `jumpLink` 可按链接字段兼容展示；
|
||||
- 查询频率按异步商品标准轮询配置。
|
||||
Reference in New Issue
Block a user