Appearance
证书链选择与交付
证书链可以按产品、密钥算法和实际签发机构提供多条交付路径。对接时先查询候选链，再使用返回的编号选择路径；不要根据品牌、证书名称或示例编号推断可用链。
接入流程
| 场景 | 调用顺序 |
|---|---|
| 创建订单前选择证书链 | 查询产品候选证书链 → 选择同一 ICA 下的 chain_id 和 cross_chain → 创建订单 |
| 查看已签发证书可选的链 | 查询证书候选链 → 从 options 中选择路径 |
| 仅本次获取使用指定链 | 查询证书候选链 → 获取证书详情时传 cross_chain |
| 后续获取都使用指定链 | 查询证书候选链 → 设置订单交付偏好 → 获取证书详情时省略 cross_chain |
| 恢复继承默认链 | 设置订单交付偏好时传 cross_chain=0 → 获取证书详情确认实际交付结果 |
| 沿用 ICA 重颁发或订阅期内续期 | 查询产品候选链时带 order_id → 在重颁发或续期请求的 certificate.cross_chain 中选择路径 |
| 重颁发或续期时切换 ICA | 不带 order_id 查询产品候选 → 选择当前 CA 账户适用的 certificate.chain_id 及同一 ICA 下的路径 → 提交重颁发或续期 |
| 获取本次交付路径的最终根证书 | 获取根证书时传 cert_id 和相同的 cross_chain 选择 |
候选链查询和偏好接口均需要 API 鉴权及订单访问权限。查询已签发证书的候选链、设置偏好还需有对应证书的提取权限；设置偏好需要订单管理权限。
chain_id 与 cross_chain
| 参数 | 含义 | 使用方式 |
|---|---|---|
chain_id | 签发中间 CA（ICA）的配置 ID | 创建、重颁发和订阅期内续期通过 certificate.chain_id 选择；从产品候选接口获取。重颁发和续期不切换 CA 账户，仅支持产品已开放、当前 CA 账户及实际算法适用的 ICA |
cross_chain | 证书的交付路径编号或兼容控制值 | 具体路径编号从 options[].cross_chain 获取；编号范围为 1000～9999，范围内不代表一定存在或可用 |
family_code | 交付链族标识 | 由订单偏好接口返回。订单偏好按链族保存；一张证书仅使用与其实际签发 ICA 匹配的链族偏好 |
选择交付路径不会改变已经签发的叶证书或实际签发 ICA。原生链与交叉链都可以有独立的 cross_chain 编号。
重颁发和续期的 ICA 配置、交付偏好随本次业务受理保存，保存成功不表示 CA 已签发。改变 ICA 不会替换历史证书；同一链族的交付偏好会影响该订单当前及历史证书。
不同接口的取值规则
| 入口 | 省略或 0 | 候选链编号 | -1 / 1 |
|---|---|---|---|
创建订单 certificate.cross_chain | 不保存指定路径偏好，按默认配置处理 | 校验通过后随订单受理保存为该链族偏好 | 关闭 / 开启对应链族的交叉链；没有登记链族时沿用旧式控制 |
重颁发、订阅期内续期 certificate.cross_chain | 保留已有偏好，不清除或重置 | 校验通过后随业务受理更新对应链族偏好 | 关闭 / 开启对应链族的交叉链，保留已保存的路径编号；没有登记链族时沿用旧式控制 |
获取证书详情查询参数 cross_chain | 按订单偏好及默认配置解析 | 仅覆盖本次获取，不保存 | 仅本次强制使用旧式不带 / 带交叉链规则 |
获取根证书 Body cross_chain（同时传 cert_id） | 按订单偏好及默认配置解析 | 仅覆盖本次获取，不保存 | 仅本次强制使用旧式不带 / 带交叉链规则 |
设置订单交付偏好 Body cross_chain | 不可省略；0 显式保存继承默认配置的偏好 | 保存指定路径偏好 | 不接受，返回参数错误 |
具体路径编号应从候选接口获取，并核对响应中的实际生效结果。
创建、重颁发和续期中的 -1 / 1 会保存交叉链开关。关闭时默认获取不使用交叉链；重新开启时，优先使用已保存或继承的交叉路径，跳过原生路径，没有匹配的登记配置时按旧式交叉链规则处理。已保存的路径编号会保留，偏好查询不返回开关状态，因此应通过证书详情确认实际交付结果。重新指定候选路径或通过偏好接口恢复继承，会清除该链族的开关覆盖。
同步签发首次创建使用与创建订单相同的参数；相同 alternative_order_id 重试按已保存的订单偏好交付，不通过重试请求修改证书链。
如何选择与确认结果
候选链接口一次返回全部当前可选路径，无需分页。options 已过滤不可新选择的路径，可以直接使用返回的 cross_chain。产品候选列表还会过滤不可选或 ICA 证书不在有效期内的条目。
查询结果不预留可用性，保存偏好和获取证书时仍会重新校验。已下架、未开放、材料无效等路径不会作为新候选返回；已保存的路径能否继续交付，以实际获取结果为准。
options=[] 表示当前没有可新选择的登记路径，不代表旧式默认链一定不能交付。产品返回的 default_chain_id 也可能不在过滤后的 chains 中，不能直接据此判断该 ICA 可选。
默认解析会考虑订单偏好、产品组默认和产品默认。将订单偏好设置为 cross_chain=0，表示跳过该订单层的指定链及旧式交叉链设置，继续使用上层默认。没有保存偏好与显式保存 0 是两种状态。
保存成功后，获取证书详情返回的 Certificate.cross_chain 表示本次实际使用的登记路径；使用旧式路径或没有登记路径编号时省略该字段。Certificate.chain_id 表示实际签发 ICA 唯一对应的配置 ID，无法唯一匹配时省略。两者均不返回 null。
恢复继承可以保存成功，但默认链仍可能无法获取。旧式交付保留兼容行为：CA 链材料缺失时仍可能返回已有叶证书，ica_pem 可能缺失。部署前应检查实际返回的 PEM 材料是否满足部署要求。
公共响应结构
日期时间使用 RFC 3339，例如 2026-10-13T08:00:00Z。示例中的编号、链族和指纹仅用于展示格式，实际值以账户下查询结果为准。
Preference 对象
| 字段 | 类型 | 说明 |
|---|---|---|
| family_code | string | 该偏好所属链族 |
| cross_chain | integer | 已保存的路径编号；0 表示未指定登记路径，实际交付还会受已保存的交叉链开关及默认配置影响 |
订单查询的 preferences=[] 表示该订单没有保存任何链族偏好。cross_chain=0 的记录可能来自显式恢复继承，也可能来自仅保存交叉链开关；本查询不返回开关状态。通过设置偏好接口提交 0 才会同时清除该链族的开关覆盖。
Candidate 对象
| 字段 | 类型 | 说明 |
|---|---|---|
| cross_chain | integer | 当前可选的交付路径编号，用于获取详情或保存偏好 |
| display_name | string | 路径显示名称 |
| chain_materials | array[object] | ICA 之上的路径材料，按从近端到最终根证书的顺序排列，不含叶证书和 ICA；元素见 MaterialIdentity |
MaterialIdentity 对象
用于显示和识别 CA 证书，不包含 PEM。材料对象本身可为 null；已返回对象中的字段均为字符串，缺少相应信息时可为空字符串。
| 字段 | 类型 | 说明 |
|---|---|---|
| sha1 | string | CA 证书 SHA-1 指纹 |
| common_name | string | 证书主题通用名称（CN） |
| subject_ou | string | 主题组织单位（OU）；有多个 OU 时仅返回第一个，未配置时为空字符串 |
| not_before | string | 生效时间 |
| not_after | string | 到期时间 |
错误与回查
证书链请求失败时，按标准响应中的 code 和 error 处理，参见证书链错误码。如果写入请求断连、超时或返回 HTTP 500/503，先查询已保存的订单偏好或订单状态，确认结果后再决定是否重试。