order_site/docs/91卡券/3.异步卡密下单.md

91卡券异步卡密下单接口

1. 接口说明

本文档为当前项目对接 91卡券 的正式技术文档，用于提交客服审核。

本项目对接场景说明：

• 91卡券 负责售卖与自动发货；
• 我方系统负责接收订单、创建任务、生成领取链接；
• 该领取链接会在后续查询订单接口中，作为最终卡密内容返回给 91卡券；
• 91卡券 再将该链接自动发给买家。

注意：

• 本接口为异步卡密下单接口；
• 首次下单成功受理后，返回 orderStatus = 10；
• 不会在该接口首次响应中直接返回最终领取链接；
• 最终链接请通过“查询订单接口”获取。

2. 请求方向

• 91卡券平台 -> 接入方系统

3. 请求 URL

请按以下地址配置：

POST https://你的域名/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. 请求示例

{
  "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

则源串示例如下：

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 已映射到 affiliate-dash 履约商品，则创建履约任务；
5. 若 productNo 尚未配置，则订单进入后台“待补全”队列，由运营补齐履约配置后重试生成任务；
6. 若传入 maxAmount，则校验成本是否超限；
7. 履约任务生成后，生成当前项目领取链接，例如：https://你的域名/#/claim/{token}；
8. 首次响应返回处理中状态，由 91卡券 后续调用查询订单接口获取最终卡密内容。

10. 响应参数

参数名	类型	必须返回	说明
orderNo	string	必须返回	商家订单号，来源 91卡券 下单请求。
outTradeNo	string	成功时必须	我方系统内部订单号。
orderStatus	int	成功时必须	订单状态。10：处理中；30：失败。 注意：当前接口为异步商品下单接口，首次响应不会返回 20。
orderCost	decimal(14,4)	成功时可返回	订单总成本，单位：元。若当前阶段无法确认，可返回 0.0000。
cards	string	非必须	当前阶段建议返回空字符串。最终卡密内容请在查询订单接口中返回。
failCode	int	失败时可返回	失败代码。
failReason	string	失败时可返回	失败原因。

11. 响应示例

11.1 受理成功

{
  "code": 200,
  "message": "接口调用成功",
  "data": {
    "orderNo": "P91KS202605040001",
    "outTradeNo": "OS202605040001",
    "orderStatus": 10,
    "orderCost": 0.0000,
    "cards": ""
  }
}

11.2 下单失败

{
  "code": 200,
  "message": "接口调用成功",
  "data": {
    "orderNo": "P91KS202605040001",
    "outTradeNo": "",
    "orderStatus": 30,
    "failCode": 1220,
    "failReason": "订单成本超出可接受范围"
  }
}

12. 对接说明

• productNo 请按我方提供的商品编号配置；
• 若 productNo 尚未配置，当前项目会先保存订单并返回 orderStatus = 10，后台补齐履约配置后可手动重试；
• 本接口成功受理后，不代表最终卡密已可交付；
• 最终交付内容为我方系统生成的领取链接，链接域名按实际部署域名配置；
• 该链接将在“查询订单接口”中，通过 cards 加密串返回；
• 建议 91卡券 将此商品配置为：异步卡密商品。