增加91卡券订单示例

2026-05-04 21:32:12 +08:00
parent 1b0a51b0bd
commit f4cc2ce623
9 changed files with 909 additions and 272 deletions
@@ -0,0 +1,154 @@
+# 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. 签名规则
+
+签名规则采用 签名规则示例 中的约定：
+
+- 除 `sign` 外，所有参数按字段名 ASCII 升序排序；
+- 使用 `key=value&key=value` 方式拼接；
+- 前后拼接商户密钥；
+- 取 `MD5`，输出 32 位大写字符串；
+- 空值参数参与签名。
+
+## 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 源串示例
+
+假设：
+
+- `userId = 1001`
+- 商户密钥为：`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&timestamp=1777867200&userId=1001&version=1.0your_secret_key
+```
+
+## 9. 业务处理规则
+
+我方系统收到请求后，按以下规则处理：
+
+1. 校验签名与时间戳；
+2. 按 `orderNo` 做幂等；
+3. 校验 `productNo` 是否已映射到当前项目的快手履约商品；
+4. 若传入 `maxAmount`，则校验成本是否超限；
+5. 创建内部订单；
+6. 创建快手 Cloud 履约任务；
+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` 请按我方提供的商品编号配置；
+- 本接口成功受理后，不代表最终卡密已可交付；
+- 最终交付内容为我方系统生成的领取链接，链接域名固定为 `221329.cc.cd`；
+- 该链接将在“查询订单接口”中，通过 `cards` 加密串返回；
+- 建议 `91卡券` 将此商品配置为：`异步卡密商品`。