# 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&timestamp=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卡券` 将此商品配置为：`异步卡密商品`。