跳到主要内容

证书展期接口

为证书订单延长服务期，按整年展期，费用从工作空间余额中扣除。

展期只延长订单的服务期，不会重新签发证书，也不会改变已签发证书的到期时间。需要重新交付或更换证书，请使用证书重签接口。

适用产品

仅部分产品支持展期，具体名单请询问客服。不支持的产品调用会返回 当前证书不支持续期。

接口地址

POST /api/v1/certificate/extend

Host: 
...

完整地址

/api/v1/certificate/extend

请求​

Content-Type: application/json

{
  "service_id": "o91bZ", // 证书编号，必填，下单时候返回的 `service_id`
  "extend_years": 1 // 展期年限，选填，1-5 的整数，不传默认 1 年
}
参数名类型必填默认值说明
service_idstring是-证书编号，下单接口返回的 service_id
extend_yearsinteger否1展期年限，取值 1-5 的整数

费用与订单​

  • 展期费用按「展期年限 × 证书当前包含的域名数量」计算，调用成功时从工作空间余额扣除。
  • 余额不足时展期失败，返回 400，message 为 Failed to extend，充值后重试。
  • 展期成功后生成一笔已支付的续期订单，并生成一条备注为 EXTEND#<service_id> 的消费流水，可用于对账。
  • 展期年限需在产品与上游支持的周期内，否则会被拒绝，详见错误码。
接口不幂等

同一证书重复调用会重复展期并重复扣费。请勿在超时后直接重试，先通过证书查询接口确认服务期是否已延长。

响应​

HTTP/1.1 200 OK

Content-Type: application/json

{
  "success": true,
  "data": {
    "service_id": "o91bZ", // 与请求传入的证书编号一致
    "order_id": "ord_xxxxx", // CA 侧订单号，售后排查时提供
    "old_validity_years": 1, // 展期前的订单服务年限
    "new_validity_years": 2, // 展期后的订单服务年限
    "new_expiration_date": "2028-01-01" // 展期后的服务期到期时间
  }
}
new_expiration_date 的格式

不同产品返回的格式可能为 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss；CA 详情查询失败时该字段为 null，此时以证书查询接口返回的服务期到期时间为准。

错误码​

HTTP 状态码message含义与处理建议
400Failed to extend余额不足，或 CA 未返回具体错误；先确认账户余额，再联系客服
400CA 返回的错误信息提交 CA 失败，按 message 内容排查；没有有效信息时请联系客服
400当前产品不支持该展期年限extend_years 不在产品允许的周期内，改用其他年限
400上游拒绝接受该展期年限的订单，请联系客服获得支持CA 侧不接受该年限，联系客服处理
404The certificate is not found, or has been cancelled or refunded证书不存在、已取消或已退款，或不属于当前 API 密钥对应的工作空间
422当前证书不支持续期证书所属产品不支持展期，或证书当前不可展期（人工锁定、提交中、退款中、订单已取消、缺少 CA 订单号）
422续期正在处理中，请稍后再试同一证书上一次展期尚未处理完成，稍后重试
422参数校验信息未提供证书编号 service_id，或 extend_years 不在 1-5 之间；响应同时带 errors 明细
422 的响应体带 errors 明细

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

{
  "success": false,
  "message": "The extend years must not be greater than 5.",
  "errors": {
    "extend_years": ["The extend years must not be greater than 5."]
  }
}

前置条件​

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

  1. 证书所属产品支持展期（具体名单请询问客服）
  2. 订单存在且未被取消
  3. 证书已提交至 CA，存在有效的 CA 订单号
  4. 证书不处于人工锁定、提交中、退款中
  5. extend_years 在产品与上游允许的周期内
  6. 工作空间余额足够支付本次展期费用

如需缩短服务期并退回费用，请使用证书缩期接口。