Appearance
常见问题 (FAQ)
本页汇总 CertCloud OpenAPI v3 对接中常见的问题与解答。
业务问题
Q1: 如何通过 API 获取 DCV 验证值？
方法一：订单详情接口
在申请订单后，通过 获取订单详情 接口的 dcv_val 字段判断：
- 字段有值 → 直接使用该验证值完成 DCV
- 字段为空 → 通过回调通知或定时轮询订单详情接口获取
方法二：预审核域名接口
对于长效验证或按域名管理的场景，通过 创建预审核域名 或 刷新域名验证值 接口获取/刷新 DCV 值。
相关文档：
Q2: 同步签发返回 202 后如何重试？
HTTP 202 表示订单已经持久化，但尚未完成签发、证书链读取和电子签名证书托管。默认等待预算约 45 秒，也可通过 sync_timeout_seconds 指定；等待容量不足时，已有订单可能提前返回 202。它不表示创建失败，也不会取消后台订单。
读取响应头 Retry-After: 3，至少等待 3 秒后，使用相同 alternative_order_id、相同产品 ID 和原始业务参数重放 POST /openapi/v3/sync-orders/{product_id}；允许调整本次 sync_timeout_seconds。完成后返回 HTTP 200，仍在处理时返回 HTTP 202，未支付或签发、交付故障返回对应错误。不要为同一次下单意图生成第二个备用 ID。
Q3: 可以修改请求体后复用同步签发的备用订单 ID 吗？
不能用同一 ID 表示不同的业务请求。alternative_order_id 是账户范围内的订单请求身份，不是备注。服务端不会比较重试请求体；映射命中后，本次 product_id、主体、有效期和其它业务字段均被忽略，服务端仍返回首次绑定的订单。仅修改 sync_timeout_seconds 是允许的，它只影响本次等待。
备用 ID 按原串匹配，不会自动去除首尾空格；重试时必须保持一致。复用结果还需要原订单的访问权限，包括所属项目的权限。
业务意图发生任何变化时必须使用新的 alternative_order_id。另请注意，最终实现为兼容旧取消流程，会在订单成功取消时改写并释放原备用 ID；取消后的新下单也必须使用新的 ID，避免原 ID 被当作全新请求再次创建订单。
Q4: 设置同步等待时间后，一定会在该时间内返回证书或 202 吗？
不会。sync_timeout_seconds 省略或为 0 时使用默认配置；显式值允许 1～120 秒。它是本次等待预算，不是签发时效承诺，也不是 HTTP 总耗时的严格上限。数据读取和网络传输可能延长响应，客户端或网关也可能提前超时。
如果发生网络超时、断连或 HTTP 500/503，不能认定订单未创建。退避后使用同一备用 ID 和原始业务参数重试，不要直接更换 ID。详见等待时间和异常后的重试规则。
Q5: 同一备用 ID 返回 sync_issuance_payment_required 怎么处理？
HTTP 422 和此错误码表示原订单仍未支付。首次支付可能尚在进行，也可能已经失败；同步接口不会再次扣费或自动补支付。保留返回的订单 ID，后续按最新状态查询；支付失败或持续未支付时需人工处理，不要换 ID 重复下单。
Q6: 组织显示审核通过，为什么同步签发仍返回审核错误？
同步申请还会核对主体归属、所选产品对应的审核类型、审核有效期、经办人或法人验证，以及申请信息是否完整。通过其他审核类型或材料已失效，仍可能返回 sync_issuance_audit_not_passed。请核对引用的 organization.id 及产品要求，无需重新提交一份组织来尝试绕过校验。