虚拟交付#

在 Halo 2.23 中，我们完善了虚拟产品的发货功能，目前支持文件资源下载、卡密发货。

#创建产品

完整的创建产品流程可参考 产品管理 文档，需要注意的是，如果产品要支持虚拟交付，需要在产品类型中选择 虚拟 产品类型。

#设置文件资源下载

创建完产品之后，我们需要进入 产品 -> 虚拟交付 页面，然后选择刚刚创建的产品。

进入设置页面之后，就可以看到 资源下载 的设置页面，我们可以点击右上方的 添加 按钮来添加文件。

• 资源类型：支持附件和静态 URL
• 资源名称：为客户显示的文件名称
• 资源描述：可以填写文件的描述信息
• 附件（当类型为附件时）：可以点击 + 按钮选择已上传的附件或者上传新的附件
• 资源地址（当类型为静态 URL 时）：可以填写文件的 URL 地址

填写完成之后，点击 保存 按钮即可。

当文件添加完成之后，我们还需要手动启用自动发货，点击右上角的 发货配置 按钮，勾选启用即可。

#设置卡密发货

进入虚拟交付设置页面之后，选择 卡密资产 选项卡，就可以看到 卡密资产 的设置页面。

我们可以点击右上方的 添加 按钮来添加卡密。

• 卡密：卡密内容，支持批量添加，一行一个
• 过期时间：卡密过期时间
• 备注：可以填写卡密的备注信息

填写完成之后点击 添加 按钮即可。

当卡密添加完成之后，我们还需要手动启用自动发货，点击右上角的 发货配置 按钮，勾选启用即可。

此外，在卡密发货配置界面中，还支持配置 远程调用配置，支持通过三方 API 来补货或者动态生成卡密并发货。

定义：

• 预获取：优先从卡密列表中选择并发货，在库存不足时才调用 API 进行补货
• 动态获取：每次发货时都调用 API 获取卡密并发货

配置说明：

• 类型：支持 预获取 和 动态获取
  • 补货配置（当类型为预获取时）
    • API 地址：补货 API 地址
    • 认证 Token：补货 API 认证 Token，用于对 API 请求进行认证
    • 阈值：可用卡密数量低于此值时触发补货
    • 每次获取的卡密数量：每次调用 API 获取的卡密数量
  • 服务器配置（当类型为动态获取时）
    • API 地址：远程生成 API 地址
    • 认证 Token：API 认证 Token，用于对 API 请求进行认证

需要注意的是，API 需要自行实现并适配 Halo 的接口标准，可以参考下方的 API 规范。

#订单相关

为产品配置好虚拟交付之后，当客户下单并支付时，系统会自动为订单进行发货流程，可以在控制台的订单详情中看到发货状态。

客户也可以在订单页面看到已发货的虚拟物品。

#API 规范

#卡密远程生成 API 规范

用户下单后，Halo 会向配置的远程地址发起请求，由你的服务实时生成或分配卡密。

#请求

POST <你配置的远程生成地址>
Content-Type: application/json
Authorization: Bearer <token>  // 配置了 token 时附带

请求体

{
  "orderItem": {
    "id": 10001,
    "orderId": 90001,
    "productId": 80001,
    "quantity": 2,
    "itemTitle": "年度会员兑换码",
    "productVariantSnapshot": {
      "id": 123,
      "name": "默认规格"
    }
  },
  "dryRun": false
}

#响应

返回卡密列表，所有卡密的 capacity 之和须不小于 orderItem.quantity。

[
  {
    "code": "ABCD-EFGH-IJKL",
    "secret": "S3cr3t-1",
    "expireAt": "2026-12-31T23:59:59Z",
    "capacity": 1
  }
]

#错误码

建议使用非 2xx 状态码表达失败，并返回结构化错误：

{
  "code": "CDK_OUT_OF_STOCK",
  "message": "No enough CDKs available",
  "requestId": "f38db1c2-2f7a-4dc3-b5a8-2d0012345678"
}

推荐错误码：

#卡密自动补货 API 规范

当密钥库存低于阈值时，Halo 会自动向配置的补货地址发起补货请求。

#请求

POST <你配置的补货地址>
Content-Type: application/json
Authorization: Bearer <token>  // 配置了 token 时附带

请求体

{
  "productVariantId": 123,
  "quantity": 50
}

#响应

返回卡密列表，实际返回数量可与请求数量不一致。

[
  {
    "code": "ABCD-EFGH-IJKL",
    "secret": "S3cr3t-1",
    "expireAt": "2026-12-31T23:59:59Z",
    "capacity": 1
  }
]

#错误码

建议使用非 2xx 状态码表达失败，并返回结构化错误：

{
  "code": "CDK_OUT_OF_STOCK",
  "message": "No enough CDKs available",
  "requestId": "f38db1c2-2f7a-4dc3-b5a8-2d0012345678"
}

推荐错误码：