文档中心

Appearance

销毁私钥 ​

POST
/openapi/v3/esign/certs/:certId/destroy

发起证书私钥销毁意愿，需由证书的控制人（企业证书为经办人，个人证书为订户本人）完成确认。接口返回 confirmUrl，需转发给该控制人打开完成确认，再通过查询意愿结果轮询结果。

前置状态：已撤销或已过期的证书才能销毁

云签受理两类证书的销毁：已撤销（REVOKED）的证书，以及已过期的证书（含状态仍为 NORMAL/FROZEN 但已过有效期——按证书 notAfter 判定，可结合查询证书状态响应的 expired=true 判断）。对未过期的 NORMAL（正常）、FROZEN（冻结）或 PENDING_ISSUE 状态的证书直接发起销毁，会被云签终态拒绝，返回 409 esign_upstream_rejected（error 形如 [-5013] 意愿绑定证书不可用），且不会创建意愿。

撤销与销毁的分工：吊销证书（通用吊销证书入口）在停止后续签名的同时，云签端会自动同步销毁私钥材料（库内私钥密文置空、密钥置为已销毁，与证书状态变更同一事务，不可恢复；证书保持「撤销」态）。销毁私钥（本接口）是控制人意愿确认后的合规销毁通道：对已过期未吊销的证书销毁私钥材料；对已吊销证书则补做销毁意愿留痕与签署口令清理（私钥通常已随吊销销毁，存量未销毁数据由云签幂等补销毁）。销毁不再改动证书状态（2026-09-03 起不再推进「已销毁」终态、不再解绑密钥）。二者均不影响历史签名——在证据留存期内仍可验签复核。

X-ES-Request-ID 必填

本接口为幂等创建类接口，请求头必须携带 X-ES-Request-ID 作为幂等键。

路径参数 ​

参数类型必填说明
certIdstring是云签证书 ID

Body 参数 ​

参数类型必填说明
controllerPersonTypestring是控制人类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）；委托人不适用，见下方警告）/ PERSONAL_SUBSCRIBER（个人订户本人）
controllerPersonIdstring是控制人 ID。须是该证书下与 controllerPersonType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId。获取方式见下方说明
reasonstring是销毁原因，随意愿进入存证与审计留痕；见下方说明

reason 必填、非空白、最长 512 字符

云签要求 reason 必填且非空白：缺失、空串或纯空格均按非法参数拒绝（上游码 -1002，本接口表现为 409 esign_upstream_rejected、error 携 [-1002]），不会创建意愿；最长 512 字符，超长同样被拒。

销毁不可逆，请一律传入真实、可追溯的业务原因（如「停服注销」），不要传占位符或统一默认文案；reason 随意愿进入存证与审计留痕。

controllerPersonId 如何获取

controllerPersonId 需通过接口反查，按人员身份取值：

  1. 用下单响应中拿到的 CertCloud 订单 ID（data.id）调用证书标识映射查询：GET /openapi/v3/esign/certs?orderId=<订单 ID>。
  2. 按本请求所指人员的实际身份，取对应字段作为 controllerPersonId：
    • 个人订户本人（controllerPersonType=PERSONAL_SUBSCRIBER）→ 取映射响应的 subjectId
    • 企业经办人（controllerPersonType=ENTERPRISE_PERSON）→ 取映射响应的 managerId；法定代表人亲自经办同取 managerId（云签按经办人统称建档，无独立法人 ID）

controllerPersonType 与所取字段必须对应（个人证书用 subjectId、企业证书用 managerId）；取错字段或填入其它来源的 ID，会返回 403 esign_person_not_in_scope。

委托人不适用本操作（云签明确禁止）

当前 CertCloud 侧对 ENTERPRISE_PERSON 的 controllerPersonId 只接受该证书映射的 managerId（经办人）；传入委托人的 delegateId（或其它企业人员 ID）会返回 403 esign_person_not_in_scope。云签侧同样明确不允许委托人发起销毁——即使透传，也会被上游以 [-5020]（企业人员类型不符）终态拒绝，并非 CertCloud 暂未放开；与签署口令 / 动态口令等个人凭据管理不同，本操作权限较重。

响应字段 ​

字段类型说明
willIdstring意愿 ID，用于经查询意愿结果按 willId 轮询确认与生效进度
confirmUrlstring转发给证书控制人（企业证书为经办人，个人证书为订户本人）打开确认的一次性链接，规则同意愿模型说明（云签域名、原样透传、请勿缓存或记录日志）
expireAtstring意愿过期时间（毫秒时间戳字符串，长整型一律字符串，见通用说明）。超过该时间后意愿转为过期终态
willStatusstring意愿当前状态，创建成功后通常为待确认态 PENDING；取值见查询意愿结果。CONFIRMED 不代表已销毁，见下方判定说明

销毁完成的判定

控制人在意愿页完成确认后（查询接口 willStatus=CONFIRMED），销毁在云签侧异步执行——CONFIRMED 不代表已销毁。以查询意愿结果返回的 businessStatus=SUCCEEDED 作为销毁完成的判定依据（FAILED 时 failReason 给出原因）。注意：销毁只翻转密钥状态、不改动证书状态——销毁后查询证书状态返回的仍是原状态（REVOKED 或原过期状态），不会出现 DESTROYED。

请求示例 ​

bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/certs/esign-cert-xxx/destroy' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -H 'X-ES-Request-ID: 2b6a0a2e-3e8b-4a0f-9c8e-1f0d3a2b5c6d' \
  -d '{
    "controllerPersonType": "ENTERPRISE_PERSON",
    "controllerPersonId": "manager-xxx",
    "reason": "密钥疑似泄露"
  }'

响应示例 ​

200成功
json
{
  "code": "0",
  "data": {
    "willId": "will-xxx",
    "confirmUrl": "https://esign.example.com/wills/portal/eyJ0eXAiOiJKV1Qi",
    "expireAt": "1730000000000",
    "willStatus": "PENDING"
  }
}

错误码 ​

HTTP 状态码code说明
400esign_request_id_requiredX-ES-Request-ID 缺失，或其值不合规——去除首尾空白后必须非空、不超过 64 个字符，且只能由字母、数字、连字符 - 与下划线 _ 组成；空白、控制字符及其他符号（:、.、/、+、中文等）均非法
400esign_invalid_body请求体非法：JSON 语法错误或字段类型不符（整数字段传字符串、字符串字段传数字等），请求体未被解析
400esign_invalid_request请求参数非法
404esign_cert_not_found证书不存在
403esign_cross_account_denied证书不属于当前账户
403esign_person_not_in_scope人员不在该证书的可用人员范围——controllerPersonId 不存在、与 controllerPersonType 不匹配，或为委托人（本操作不允许，见上方警告）
409esign_idempotency_conflict复用同一 X-ES-Request-ID 但请求体与首次发起不一致；不回放旧意愿、也不创建新意愿，请改用新的 X-ES-Request-ID。见X-ES-Request-ID 幂等键
409esign_upstream_rejected当前请求被云签终态拒绝；error 为 [上游码] 文案，仅供人工排查、不可据其编程。修正输入或证书状态后，使用新的 X-ES-Request-ID 再发起。见上游错误响应与重试
409esign_upstream_error云签暂时性失败；error 为 [上游码] 文案，仅供人工排查、不可据其编程。可使用相同 X-ES-Request-ID 稍后安全重试。见上游错误响应与重试