创建订单

7. 订单

7.1 创建订单

• 请求方式：POST

• 请求地址：/orders/create

创建订单前不需要再次查询商品详情或下单模板。卡密商品只提交商品、规格和数量；充值商品还要提交第三方在商品对接时保存的下单模板版本和充值资料。请求中不提交价格，平台按下单时该账户的最新销售价格计算，金额最多保留两位小数；余额实际扣款、订单金额和返回的 data.amount 完全一致。如果价格在商品对接后发生变化，本单仍按下单时的最新价格成交。

请求：

{
  "clientOrderRef": "PO-20260728-0001",
  "productRef": 1001,
  "units": 1,
  "purchaseSchemaRevision": 1753776000,
  "orderCallbackUrl": "https://buyer.example.com/kys/orders/PO-20260728-0001/events",
  "purchaseEntries": [
    {
      "account": "13800138000",
      "region": "guangdong"
    }
  ]
}

请求字段：

返回字段：

返回示例（对应第 6.4 节的充值模板和上面的下单请求，订单等待处理）：

{
  "code": 0,
  "message": "success",
  "data": {
    "clientOrderRef": "PO-20260728-0001",
    "platformOrderRef": "202607280001",
    "productRef": 1001,
    "variantRef": 0,
    "units": 1,
    "amount": 100.00,
    "orderState": "pending",
    "refundedAmount": 0.00,
    "allowedActions": ["requestCancellation", "openCase"],
    "createdAt": 1785216000,
    "updatedAt": 1785216000,
    "rechargeResult": ""
  },
  "requestId": "req_01K0EXAMPLE"
}

充值商品的 entryMode：

• purchaseEntries 中的每个对象代表一组下单资料，字段名直接使用模板返回的 fieldRef，字段值填写第三方用户输入的内容。

• purchaseFields 为空：充值商品提交空数组。

• singleEntry：purchaseFields 不为空时，purchaseEntries 必须只有一个对象；当前模板未开启批量时 units 必须为 1。

• oneEntryPerUnit：每件商品提交一个对象，数组长度必须等于 units。

variantRef：

• 单规格商品可以不填写，平台自动使用默认规格。

• 多规格商品必须填写商品详情返回的规格编号。

如果模板或数量规则已经变化，平台会在扣款前返回 PURCHASE_SCHEMA_CHANGED。第三方重新查询 /goods/tpl、更新本地下单表单后，继续使用原来的 clientOrderRef 再次提交。

clientOrderRef 长度为 1 至 64 个字符，只能使用字母、数字、短横线和下划线，并且在当前采购账户内唯一：

• 网络超时或没有收到明确结果时，必须使用原 clientOrderRef 和原下单内容重试。平台会返回第一次创建的原订单，不会再次扣款或重复下单。

• 同一 clientOrderRef 不能改成另一件商品、另一规格、另一数量或不同充值资料，否则返回 IDEMPOTENCY_CONFLICT。

• 重试时传入不同的 orderCallbackUrl 不会修改原订单，仍以原订单第一次保存的地址为准。

• 请求在订单创建前因参数、模板、余额或库存校验失败时不会占用该编号；修正后仍可复用原编号。

orderCallbackUrl 选填：

• 用于接收该订单的状态、卡密就绪和退款事件。

• 不要求账户先保存默认回调地址，也不要求与默认地址使用相同域名。平台不会在下单前向该地址发送验证请求。

• 填写时必须使用公网 HTTPS。URL 路径和查询参数可以按订单变化。

• 订单创建成功后不能更换该订单的回调地址。

• URL 不能包含用户名或密码、# 片段或 IP 地址，也不能返回 HTTP 跳转。URL 可以包含查询参数。

• 提交该地址后，本订单的状态、卡密和退款消息优先发送到这里。

• 订单成功创建后，平台自动创建或续期该商品订阅，并把该地址绑定为商品通知目标；后续 product.changed 只向该地址推送一次，不再同时推送账户默认地址。

• 同一商品以后有新订单使用不同的 orderCallbackUrl 时，商品通知改发到最新地址。

• 不填写 orderCallbackUrl 时，不会修改这个商品当前有效订阅已经绑定的地址。商品从未绑定过订单地址时，每条商品消息生成时使用当时的默认回调地址。取消订阅或执行 clearAll 会立即删除商品绑定；订阅到期后旧绑定不再使用，后续重新订阅或订单续期且没有提交新地址时清除旧绑定。

• 不填写 orderCallbackUrl 时，平台不会在创建订单时复制默认地址。以后每条订单、卡密、退款或关联售后消息生成时，使用当时的账户默认回调地址。

• 默认回调地址修改后只影响之后新生成的消息；已经进入发送流程的消息仍使用原地址。

• 某条消息生成时既没有订单地址也没有默认地址，就不发送该条 Webhook。订单仍然正常创建，第三方通过订单详情查询状态、卡密和退款结果。

订单只有在余额扣款成功后才会创建。HTTP 2xx 表示订单已经创建，但不表示充值或发卡已经完成；最终结果看 orderState。余额不足时不会创建订单，也不会改用其他支付方式。