157 lines
5.3 KiB
Markdown
157 lines
5.3 KiB
Markdown
# 91卡券异步卡密下单接口
|
||
|
||
## 1. 接口说明
|
||
|
||
本文档为当前项目对接 `91卡券` 的正式技术文档，用于提交客服审核。
|
||
|
||
本项目对接场景说明：
|
||
|
||
- `91卡券` 负责售卖与自动发货；
|
||
- 我方系统负责接收订单、创建任务、生成领取链接；
|
||
- 该领取链接会在后续查询订单接口中，作为最终卡密内容返回给 `91卡券`；
|
||
- `91卡券` 再将该链接自动发给买家。
|
||
|
||
注意：
|
||
|
||
- 本接口为**异步卡密下单接口**；
|
||
- 首次下单成功受理后，返回 `orderStatus = 10`；
|
||
- **不会**在该接口首次响应中直接返回最终领取链接；
|
||
- 最终链接请通过“查询订单接口”获取。
|
||
|
||
## 2. 请求方向
|
||
|
||
- `91卡券平台 -> 接入方系统`
|
||
|
||
## 3. 请求 URL
|
||
|
||
请按以下地址配置：
|
||
|
||
```text
|
||
POST https://221329.cc.cd/api/v1/open/91/orders/create
|
||
```
|
||
|
||
## 4. 请求方式
|
||
|
||
- `POST`
|
||
- `Content-Type: application/json;charset=utf-8`
|
||
|
||
## 5. 签名规则
|
||
|
||
签名规则采用 签名规则示例 中的约定：
|
||
|
||
- 仅使用请求 JSON body 中实际传入的参数参与签名；
|
||
- 除 `sign` 外，所有 body 参数按字段名 ASCII 升序排序；
|
||
- 使用 `key=value&key=value` 方式拼接；
|
||
- 前后拼接商户密钥；
|
||
- 取 `MD5`，输出 32 位大写字符串；
|
||
- 已传入的空值参数参与签名；
|
||
- 不要额外加入 `userId`、商户号、内部配置项或未传入的可选字段。
|
||
|
||
## 6. 请求参数
|
||
|
||
| 参数名 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `orderNo` | 是 | string | 商家订单号，唯一，用于幂等处理。 |
|
||
| `productNo` | 是 | string | 接入方商品编号。建议与我方内部履约 SKU 一一对应。 |
|
||
| `buyNum` | 是 | int | 购买数量。 |
|
||
| `maxAmount` | 否 | string | 商家可接受最大成本金额。值为整单金额，非单价。若传值，则我方按该金额校验，超出时返回失败。 |
|
||
| `callbackUrl` | 否 | string | 由 `91卡券` 提供的回调地址。当前项目可接收但不依赖该字段完成主流程。 |
|
||
| `timestamp` | 是 | long | 10 位秒级 Unix 时间戳，用于请求时效校验。 |
|
||
| `version` | 是 | string | 固定传 `1.0`。 |
|
||
| `sign` | 是 | string | 签名。 |
|
||
|
||
## 7. 请求示例
|
||
|
||
```json
|
||
{
|
||
"orderNo": "P91KS202605040001",
|
||
"productNo": "KS-CLOUD-SKU-001",
|
||
"buyNum": 1,
|
||
"maxAmount": "0.0000",
|
||
"callbackUrl": "https://cb.example.com/notify/91/order",
|
||
"timestamp": 1777867200,
|
||
"version": "1.0",
|
||
"sign": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|
||
}
|
||
```
|
||
|
||
## 8. MD5 源串示例
|
||
|
||
假设：
|
||
|
||
- 商户密钥为：`your_secret_key`
|
||
|
||
则源串示例如下：
|
||
|
||
```text
|
||
your_secret_keybuyNum=1&callbackUrl=https://cb.example.com/notify/91/order&maxAmount=0.0000&orderNo=P91KS202605040001&productNo=KS-CLOUD-SKU-001×tamp=1777867200&version=1.0your_secret_key
|
||
```
|
||
|
||
## 9. 业务处理规则
|
||
|
||
我方系统收到请求后，按以下规则处理：
|
||
|
||
1. 校验签名与时间戳；
|
||
2. 按 `orderNo` 做幂等；
|
||
3. 将订单作为 `91卡券` 来源订单写入当前项目；
|
||
4. 若 `productNo` 已映射到快手 Cloud 履约商品，则创建履约任务；
|
||
5. 若 `productNo` 尚未配置，则订单进入后台“待补全”队列，由运营补齐履约配置后重试生成任务；
|
||
6. 若传入 `maxAmount`，则校验成本是否超限；
|
||
7. 履约任务生成后，生成当前项目领取链接，例如：`https://221329.cc.cd/#/claim/{token}`；
|
||
8. 首次响应返回处理中状态，由 `91卡券` 后续调用查询订单接口获取最终卡密内容。
|
||
|
||
## 10. 响应参数
|
||
|
||
| 参数名 | 类型 | 必须返回 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `orderNo` | string | 必须返回 | 商家订单号，来源 `91卡券` 下单请求。 |
|
||
| `outTradeNo` | string | 成功时必须 | 我方系统内部订单号。 |
|
||
| `orderStatus` | int | 成功时必须 | 订单状态。`10`：处理中；`30`：失败。<br>注意：当前接口为异步商品下单接口，首次响应**不会返回 `20`**。 |
|
||
| `orderCost` | decimal(14,4) | 成功时可返回 | 订单总成本，单位：元。若当前阶段无法确认，可返回 `0.0000`。 |
|
||
| `cards` | string | 非必须 | 当前阶段建议返回空字符串。最终卡密内容请在查询订单接口中返回。 |
|
||
| `failCode` | int | 失败时可返回 | 失败代码。 |
|
||
| `failReason` | string | 失败时可返回 | 失败原因。 |
|
||
|
||
## 11. 响应示例
|
||
|
||
### 11.1 受理成功
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "接口调用成功",
|
||
"data": {
|
||
"orderNo": "P91KS202605040001",
|
||
"outTradeNo": "OS202605040001",
|
||
"orderStatus": 10,
|
||
"orderCost": 0.0000,
|
||
"cards": ""
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11.2 下单失败
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "接口调用成功",
|
||
"data": {
|
||
"orderNo": "P91KS202605040001",
|
||
"outTradeNo": "",
|
||
"orderStatus": 30,
|
||
"failCode": 1220,
|
||
"failReason": "订单成本超出可接受范围"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 12. 对接说明
|
||
|
||
- `productNo` 请按我方提供的商品编号配置；
|
||
- 若 `productNo` 尚未配置，当前项目会先保存订单并返回 `orderStatus = 10`，后台补齐履约配置后可手动重试；
|
||
- 本接口成功受理后，不代表最终卡密已可交付；
|
||
- 最终交付内容为我方系统生成的领取链接，链接域名固定为 `221329.cc.cd`；
|
||
- 该链接将在“查询订单接口”中，通过 `cards` 加密串返回；
|
||
- 建议 `91卡券` 将此商品配置为：`异步卡密商品`。
|