跳到主要内容

证书缩期接口

缩短证书订单的服务期，按整年取消尚未到期的续期订单，费用退回工作空间余额。

缩期只作用于续期订单，不会缩短首次购买的基础服务期，也不会重新签发或吊销已签发的证书。

适用产品

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

接口地址

POST /api/v1/certificate/shrink

Host: 
...

完整地址

/api/v1/certificate/shrink

请求​

Content-Type: application/json

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

退款规则​

  • 从最近一次已支付的续期订单开始，向前依次取消。
  • 整个续期订单被取消时，退还该订单的全部实付金额。
  • 只取消订单中的部分年限时，按取消年限的占比退还实付金额，并把该续期订单的期限改为剩余年限。
  • 退款退回该订单原支付币种的工作空间余额，并生成一条备注为 SHRINK#<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": 3, // 缩期前的订单服务年限
    "new_validity_years": 2, // 缩期后的订单服务年限
    "new_expiration_date": "2027-01-01" // 缩期后的服务期到期时间
  }
}
new_expiration_date 的格式

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

错误码​

HTTP 状态码message含义与处理建议
400CA 返回的错误信息，或 Failed to shrink提交 CA 失败，按 message 内容排查；没有有效信息时请联系客服
404The certificate is not found, or has been cancelled or refunded证书不存在、已取消或已退款，或不属于当前 API 密钥对应的工作空间
422当前证书不支持缩期证书所属产品不支持缩期，或证书当前不可操作（人工锁定、提交中、退款中、订单已取消、缺少 CA 订单号）
422没有可取消的续期没有已支付的续期订单（未展期过，或续期订单已全部取消），没有可缩短的年限
422无法缩期 1 年，续期订单不足shrink_years 超过已支付续期订单的总年限，减少年限后重试
422无法缩期 1 年，续期订单期限不匹配缩期后的剩余年限无法落成完整的订单周期，减少年限后重试
422缩期正在处理中，请稍后再试同一证书上一次缩期尚未处理完成，稍后重试
422参数校验信息未提供证书编号 service_id，或 shrink_years 不在 1-5 之间；响应同时带 errors 明细
422 的响应体带 errors 明细

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

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

前置条件​

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

  1. 证书所属产品支持缩期（具体名单请询问客服）
  2. 订单存在且未被取消，证书不处于人工锁定、提交中、退款中
  3. 证书已提交至 CA，存在有效的 CA 订单号
  4. 存在已支付的续期订单
  5. shrink_years 不超过已支付续期订单的总年限
  6. 缩期后的剩余年限为 1-5 年的整年周期

如需重新购买已缩期的年限，请使用证书展期接口，按当前售价计费。