文档中心

Appearance

设置订单交付偏好 ​

PUT
/openapi/v3/orders/:id/delivery-chain-preference

为订单保存某个链族的交付偏好。服务端通过请求中的已签发证书确定实际 ICA 和链族，无需传入 family_code。需要订单管理及对应证书的提取权限；仅有审核权限不能执行此操作。

本接口只修改后续获取证书时使用的交付路径，不触发重颁发或续期，不改变叶证书、私钥和实际签发 ICA。只想本次使用其他路径时，请在获取证书详情时传入查询参数 cross_chain。

请求参数 ​

路径参数 ​

参数类型必填说明
idstring是订单 ID

Body 参数 application/json ​

参数类型必填说明
cert_idstring是属于该订单且可提取的已签发证书 ID；用于确定要更新的链族
cross_chaininteger是0：显式继承默认配置；或查询证书候选链返回的可选路径编号（1000～9999）。
必须是 JSON 整数；省略、null、字符串、小数、溢出、-1、1 或范围外编号均不接受。
范围内但不存在的编号返回 delivery_chain_unknown_selector；不能仅凭编号范围判断可用性。

返回数据 ​

字段类型说明
order_idstring订单 ID
cert_idstring用于确定链族的证书 ID
family_codestring本次更新的链族
cross_chaininteger本次保存的路径编号；0 表示显式继承默认配置

请求示例 ​

先查询证书候选链，再将示例编号 1002 替换为 options[].cross_chain 中的编号；同时替换订单、证书 ID 和鉴权值。

bash
curl -X PUT 'https://api.certcloud.cn/openapi/v3/orders/TIT6R0qv/delivery-chain-preference' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  --data '{"cert_id":"F7vbIVYL","cross_chain":1002}'

恢复继承时，使用同一接口并将请求体改为：

json
{"cert_id":"F7vbIVYL","cross_chain":0}

响应示例 ​

以下编号、名称和指纹仅为示例；实际选择请使用本账户接口返回的值。

200成功
json
{
  "code": "success",
  "data": {
    "order_id": "TIT6R0qv",
    "cert_id": "F7vbIVYL",
    "family_code": "example-rsa",
    "cross_chain": 1002
  }
}

保存与回查 ​

  • cross_chain=0 表示显式保存继承配置，不是删除记录，也不是“禁用交叉链”。它只更新该证书对应链族，不清除订单的其他链族偏好。
  • 恢复继承可以成功保存，即使默认路径当前无法交付。HTTP 200 表示偏好已保存；请再获取证书详情，检查实际返回的证书和路径。
  • 指定路径或恢复继承会清除该链族已保存的交叉链开关覆盖；保存后，不带 cross_chain 调用证书详情即可使用保存的偏好；显式查询参数仍可覆盖单次获取。
  • 写入返回 HTTP 500/503、超时或连接中断时，不能仅据此判断保存失败。先查询订单交付偏好核对该链族的保存值，再获取证书详情确认实际交付结果，避免直接回滚或覆盖。

具体错误码、HTTP 状态和重试规则见证书链错误码。