文档中心

Appearance

查询证书状态 ​

GET
/openapi/v3/esign/certs/:certId

查询云签证书的当前状态，可用于确认销毁的最终结果。

停轮公式：只有一种情况应该继续轮询

继续轮询  ⟺  status === "PENDING_ISSUE"  且  hostingFailed !== true

其余一切情况一律停止轮询——包括 NORMAL、FROZEN、REVOKED、VOIDED，以及本文档未列出的任何未知取值。

两个最容易漏掉、会导致无限轮询的停轮信号：

  • hostingFailed: true——托管重试已经停止，status 会永久停留在 PENDING_ISSUE，再怎么轮询都不会变化，须转人工处理。
  • VOIDED——待签发记录已作废（CA 拒签、订单取消等），是终态，不会再转为 NORMAL。

把未知取值也归入「停轮」，是为了避免云签后续新增状态枚举时把您的轮询逻辑卡死。请勿按「只要不是 NORMAL 就继续轮」实现——那正是死循环的来源。轮询建议 3~5 秒一次，并自行设置总时长上限。

路径参数 ​

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

响应字段 ​

字段类型说明
certIdstring云签证书 ID（回显路径参数）
statusstring证书状态，取值见下表
expiredboolean证书是否已过有效期。与 status 相互独立：过期证书的 status 仍可能是 NORMAL
certPemstring证书 PEM。仅 status=NORMAL 且服务端成功取到证书材料时出现，见下方说明
chainPemarray<string> | null证书链 PEM 列表。出现条件同 certPem；采用尽力重建，可能为 null、空数组或缺项
hostingFailedboolean仅托管重试已停止时出现且恒为 true，见下方托管失败字段
failReasonstring托管失败原因，仅随 hostingFailed 出现，见下方托管失败字段

certPem / chainPem 仅 NORMAL 且材料就绪时返回

certPem 与 chainPem 仅在 status 为 NORMAL 且服务端成功取到证书材料时返回；其余状态下响应中不包含这两个字段。chainPem 类型为 array<string> | null，证书链采用尽力重建：极少数情况下可能为 null、空数组或缺项，不代表证书本身异常——验证链失败时建议自行按 certPem 中的颁发者信息补链。

status 取值 ​

取值说明
NORMAL正常（含解冻后恢复正常）
FROZEN已冻结
REVOKED已撤销（停止后续签名，私钥材料已同步销毁、不可恢复）。这是销毁私钥的典型前置状态——销毁同时受理已过期证书（含过期的 NORMAL/FROZEN，按证书有效期判定、见响应 expired 字段）；未过期的正常/冻结态会被拒绝
DESTROYED已销毁（已取消，2026-09-03 起不再出现）：销毁私钥只翻转密钥状态、不改动证书状态——吊销时云签已自动销毁私钥材料；经销毁私钥意愿销毁后，证书仍保持 REVOKED 或原过期状态
VOIDED已作废——待签发记录被作废（CA 拒签、订单取消等原因，由 CertCloud 在证书尚未签发时发起）。终态，不会再转为 NORMAL：该 certId 及其密钥已回收，无法用于任何签署或生命周期操作，需要证书请重新创建订单。见到此值请立即停止轮询
PENDING_ISSUE已分配云签证书 ID，但尚未完成云签托管：可能仍在签发，也可能证书已签发但回推托管尚未成功。此状态无 certPem/chainPem。这是唯一应该继续轮询的状态，且仅在响应未返回 hostingFailed 时成立——一旦同时返回 hostingFailed: true，表示重试已停止，继续轮询永远不会有结果（见下节）。注意：certId 尚未生成的场景不会出现在本接口——那时证书标识映射查询返回的 status 为空

托管失败字段 ​

托管重试并非无限进行。当系统判定继续重试无意义时会停止，并在响应中追加以下字段：

字段类型说明
hostingFailedboolean仅在托管重试已停止时出现且恒为 true；托管仍在进行中时该字段不存在
failReasonstring失败原因，形如 [错误码] 描述。部分失败无法对外披露具体原因时返回统一提示，此时请联系技术支持并提供 X-ES-Request-ID

停止重试的判定：云签明确拒绝（如证书链不匹配、证书状态非法）时首次即停；网络异常、网关错误等则重试若干次后停止，整个窗口约 30 分钟。

hostingFailed 出现后请停止轮询

hostingFailed: true 表示这张证书不会再自动完成托管，status 会一直停留在 PENDING_ISSUE，继续轮询不会有任何变化。此时证书本身通常已经正常签发、可以下载，只是尚未托管到云签，因而暂不能用于云签签署（发起签名意愿会失败）。

恢复需要人工介入，请携带 certId 与 failReason 联系技术支持。恢复完成后本接口的 status 会转为 NORMAL 且这两个字段消失。

请求示例 ​

bash
curl -X GET 'https://api.certcloud.cn/openapi/v3/esign/certs/esign-cert-xxx' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

响应示例 ​

200成功（NORMAL 状态，含证书内容）
json
{
  "code": "0",
  "data": {
    "certId": "esign-cert-xxx",
    "status": "NORMAL",
    "expired": false,
    "certPem": "-----BEGIN CERTIFICATE-----...",
    "chainPem": [
      "-----BEGIN CERTIFICATE-----...",
      "-----BEGIN CERTIFICATE-----..."
    ]
  }
}
200成功（非 NORMAL 状态，不含证书内容）
json
{
  "code": "0",
  "data": {
    "certId": "esign-cert-xxx",
    "status": "REVOKED",
    "expired": false
  }
}
200成功（托管失败，已停止重试）
json
{
  "code": "0",
  "data": {
    "certId": "esign-cert-xxx",
    "status": "PENDING_ISSUE",
    "expired": false,
    "hostingFailed": true,
    "failReason": "[-4011] 证书不是由指定CA证书链签发"
  }
}

错误码 ​

HTTP 状态码code说明
404esign_cert_not_found证书不存在
403esign_cross_account_denied证书不属于当前账户