跳到主要内容

证书重交付接口

取多年期订单服务期内的下一次交付。

当用户购买的是 1 年 / 2 年，但 CA 每次只交付一张短周期证书（如 90 天）时， 服务期内需要交付多次。本次交付临近到期、服务期还有剩余时，调用此接口取下一次交付， 而不需要用户重新付费续费。

Certum、GlobalSign 品牌不支持本接口

Certum、GlobalSign 品牌的产品不支持本接口，调用会被拒绝并返回 请使用 /api/v1/certificate/reissue 重签名以重新交付下一轮证书。

这两个品牌要求每次重签名都必须更换 CSR，而本接口按定义复用证书当前的 CSR，两者互斥。 请改用证书重签接口，在请求中自带一份新的 csr 重签名， 以交付下一期证书。

接口地址

POST /api/v1/certificate/redeliver

Host: 
...

完整地址

/api/v1/certificate/redeliver

请求​

Content-Type: application/json
Content-Length: 24

{
  "service_id": "o91bZ" // 证书编号，必填，下单时候返回的 `service_id`
}

响应​

HTTP/1.1 200 OK

Content-Type: application/json
Content-Length: 970

{
  "success": true,
  "data": {
    "hash_id": "o91bZ", // 证书编号，与请求传入的 service_id 一致
    "dcv_need_verify": true, // 本次交付需要重新做域名验证，下面才会带 dcv
    "dcv": { // 本次交付**重新生成**的域名验证信息，按域名索引，每个 SAN 一条（下例只展示一条）
      "example.com": {
        "domain": "example.com",
        "type": "dns", // 验证方式沿用证书原有的选择：dns / http / https / email
        "subdomain": "",
        "topleveldomain": "example.com",
        "status": "pending", // 重交付后一律回到 pending，需要重新验证
        "ca_dcv_status": null, // CA 侧的验证状态原文，未回写时为 null
        "validated_at": null,
        "ca_dcv_raw": null,
        "dns": {
          "type": "TXT",
          "hostname": "_dnsauth",
          "fullname": "_dnsauth.example.com",
          "value": "9f2c37e0a5d14b8fb0c6e1f7d2a48c3e5b6a0d9f4c7e1a3b5d8f0c2e4a6b8d0f"
        },
        "http": {
          "filename": "fileauth.txt",
          "filecontent": "9f2c37e0a5d14b8fb0c6e1f7d2a48c3e5b6a0d9f4c7e1a3b5d8f0c2e4a6b8d0f",
          "filepath": "/.well-known/pki-validation/",
          "filefullpath": "/.well-known/pki-validation/fileauth.txt",
          "url": "http://example.com/.well-known/pki-validation/fileauth.txt"
        },
        "https": {
          "filename": "fileauth.txt",
          "filecontent": "9f2c37e0a5d14b8fb0c6e1f7d2a48c3e5b6a0d9f4c7e1a3b5d8f0c2e4a6b8d0f",
          "filepath": "/.well-known/pki-validation/",
          "filefullpath": "/.well-known/pki-validation/fileauth.txt",
          "url": "https://example.com/.well-known/pki-validation/fileauth.txt"
        }
      }
    }
  }
}
dcv 就是下一步要用的新验证值

仅 dcv_need_verify 为 true（SSL.com、Keymatic）时响应才带 dcv。 dcv.<域名>.type 指明该域名本次采用的验证方式，按它取对应那一块里的 value（dns） 或 filecontent（http / https）配置即可。非通配域名会把 dns / http / https 三块一并返回，只按 type 那一块操作，其余两块是备用的验证方式； 通配域名（*.）与 Certum 产品只返回其支持的那一块。

type 为 email 时没有值块可取，CA 会直接向该域名的验证邮箱发验证邮件。

错误码​

HTTP 状态码message含义与处理建议
400请使用 /api/v1/certificate/reissue 重签名以重新交付下一轮证书证书所属产品要求重签名必须更换 CSR，而本接口按定义复用证书当前的 CSR，两者互斥。请改用证书重签接口并自带一份新的 csr
400当前证书没有可更新的交付次数（服务期已结束或本次交付已覆盖服务期）服务期已到期，或本次交付已经覆盖完整个服务期。此时应引导用户续费，而不是调用本接口
400此账号已禁用重签名功能当前工作空间被关闭了重签名能力，需联系平台开通
400订单正处于人工跟进中，已锁定，暂不支持更新订单被人工锁定（客服跟进中），暂不支持更新
400证书正在提交中，请稍后再试上一次提交尚未完成，请稍后重试
400更新正在处理中，请稍后再试60 秒内已有一次更新在飞，请等待后重试
400更新失败，请联系客服提交 CA 失败（或返回 CA 的原始错误信息）
404The certificate is not found, or has been cancelled or refunded证书不存在，或不属于当前 API 密钥对应的工作空间
422The service ID is required未提供证书编号 service_id
422 的响应体带 errors 明细

参数校验失败（422）时，除了 message 外还会返回 errors 字段，标明是哪个参数不合法：

{
  "success": false,
  "message": "The service ID is required",
  "errors": {
    "service_id": ["The service ID is required"]
  }
}
调用后证书会回到「待域名验证」状态

调用成功后，证书会被重置为待验证状态：

  • ca_status 变为 pending
  • issued_at 置空
  • 已签发的证书内容（cert.<keytype>.cert）被清空

这意味着旧证书不再可用，需要等待本次交付完成并重新下载证书后再部署。 请在业务侧做好提示，避免用户在等待期间误以为证书丢失。

⚠️ 要不要重做域名验证，看响应的 dcv_need_verify

SSL.com、Keymatic 品牌每次交付都要重新做一次域名验证，响应里 dcv_need_verify 为 true，并带上重新生成的 dcv：

  • 验证方式（DNS 解析 / 文件 / 邮箱）沿用证书原有的选择，不会改变
  • 但验证值会重新生成 —— DNS 记录值、文件内容都会变成新的一串， 调用前已经配好的域名解析记录或校验文件会失效

其余品牌 dcv_need_verify 为 false，CA 沿用已有的域名验证记录， 响应不带 dcv，用户侧无需任何操作。

按以下顺序处理：

  1. 调用本接口
  2. dcv_need_verify 为 false → 跳过验证环节，直接等本次交付签发完成
  3. dcv_need_verify 为 true → 从响应 dcv 里取该域名 type 对应那一块的新值 （dns.value / http.filecontent / https.filecontent），提示用户重新配置 DNS 解析或上传校验文件
  4. 调用检查 DCV 接口触发 CA 校验

响应里拿到 验证信息获取中... 占位符时，改用证书状态接口取真实值。

如果业务侧无法引导用户重新配置，请不要对 SSL.com、Keymatic 调用本接口，改用 证书重签接口（重签同样会重置 DCV，需一并评估）。

前置条件​

调用前请确认以下条件全部满足，否则会被拒绝：

  1. 证书已签发（未签发的证书请走正常的 DCV 流程，不要用本接口）
  2. 订单存在且未被取消
  3. 服务期未过期
  4. 服务期晚于当前证书的到期时间（即服务期还有剩余，存在下一次交付）
  5. 证书所属产品没有「重签名必须更换 CSR」的限制（Certum、GlobalSign 品牌属于此类，请改用证书重签接口）