207 lines
6.0 KiB
Markdown
207 lines
6.0 KiB
Markdown
# 91卡券查询订单接口
|
||
|
||
## 1. 接口说明
|
||
|
||
本文档为当前项目对接 `91卡券` 的正式技术文档，用于提交客服审核。
|
||
|
||
本接口用于在异步卡密下单后，由 `91卡券` 主动查询订单状态与最终卡密内容。
|
||
|
||
当前项目的最终交付物不是传统卡号密码，而是：
|
||
|
||
- 我方系统生成的**领取链接**；
|
||
- 该链接将作为最终卡密内容，通过 `cards` 字段返回给 `91卡券`；
|
||
- `91卡券` 再使用自动发货能力，将该领取链接展示给买家。
|
||
|
||
## 2. 请求方向
|
||
|
||
- `91卡券平台 -> 接入方系统`
|
||
|
||
## 3. 请求 URL
|
||
|
||
请按以下地址配置：
|
||
|
||
```text
|
||
POST https://你的域名/api/v1/open/91/orders/query
|
||
```
|
||
|
||
## 4. 请求方式
|
||
|
||
- `POST`
|
||
- `Content-Type: application/json;charset=utf-8`
|
||
|
||
## 5. 签名规则
|
||
|
||
签名规则采用 2.签名规则示例 中的约定：
|
||
|
||
- 仅使用请求 JSON body 中实际传入的参数参与签名；
|
||
- 除 `sign` 外，所有 body 参数按字段名 ASCII 升序排序；
|
||
- 使用 `key=value&key=value` 方式拼接；
|
||
- 前后拼接商户密钥；
|
||
- 取 `MD5`，输出 32 位大写字符串；
|
||
- 已传入的空值参数参与签名；
|
||
- 不要额外加入 `userId`、商户号、内部配置项或未传入的可选字段。
|
||
|
||
## 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 源串示例
|
||
|
||
假设：
|
||
|
||
- 商户密钥为：`your_secret_key`
|
||
|
||
则源串示例如下：
|
||
|
||
```text
|
||
your_secret_keyorderNo=P91KS202605040001×tamp=1777867260&version=1.0your_secret_key
|
||
```
|
||
|
||
## 9. 业务处理规则
|
||
|
||
我方系统收到查询请求后，按以下规则返回：
|
||
|
||
1. 校验签名与时间戳；
|
||
2. 根据 `orderNo` 查询内部订单；
|
||
3. 若订单存在但商品履约配置尚未补齐，返回 `orderStatus = 10`；
|
||
4. 若订单存在但领取链接尚未准备完成，返回 `orderStatus = 10`；
|
||
5. 若领取链接已生成，可交付，返回 `orderStatus = 20`；
|
||
6. 若订单无法履约，返回 `orderStatus = 30`；
|
||
7. 当返回 `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://你的域名/#/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://你的域名/#/claim/abc123xyz",
|
||
"cardPwd": "",
|
||
"expireTime": "2026-05-05 12:00:00",
|
||
"jumpLink": "https://你的域名/#/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://你的域名/#/claim/abc123xyz",
|
||
"cardPwd": "",
|
||
"expireTime": "2026-05-05 12:00:00",
|
||
"jumpLink": "https://你的域名/#/claim/abc123xyz"
|
||
}
|
||
]
|
||
```
|
||
|
||
### 12.3 查询失败
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "接口调用成功",
|
||
"data": {
|
||
"orderNo": "P91KS202605040001",
|
||
"outTradeNo": "OS202605040001",
|
||
"orderStatus": 30,
|
||
"failCode": 1204,
|
||
"failReason": "商品未配置或订单无法履约"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 13. 对接说明
|
||
|
||
- 本接口是 `91卡券` 自动发货的关键接口；
|
||
- 当返回 `orderStatus = 20` 时，表示我方已准备好最终交付内容；
|
||
- 当返回 `orderStatus = 10` 时，可能是履约任务正在准备，也可能是后台正在补齐 `productNo` 对应的履约配置；
|
||
- 最终交付内容是领取链接，不是传统卡号密码；
|
||
- 领取链接域名按实际部署域名配置；
|
||
- 买家收到链接后，会进入我方系统领取页完成后续快手核销与履约流程；
|
||
- 建议 `91卡券` 侧确认：
|
||
- `cards.cardNo` 可直接展示完整链接；
|
||
- `jumpLink` 可按链接字段兼容展示；
|
||
- 查询频率按异步商品标准轮询配置。
|