证书标识映射查询

GET

/openapi/v3/esign/certs

补充接口（不在原 9 个契约端点之内）

/esign/** 下的其余接口全部以云签 certId 为定位锚点，且销毁私钥的 controllerPersonId、变更人员联系信息的 personId 还需要云签的订户 / 经办人 ID —— 这些标识此前只存在于 CertCloud 内部，调用方下单后只能拿到 CC 的订单 ID 与证书 ID，无从获取云签侧标识。本接口按调用方下单响应中一定能拿到的 orderId 为查询键，补上这一契约缺口，是调用方获取上述标识的唯一途径。

按 CertCloud 订单 ID 查询该订单对应的云签标识映射，包括云签证书 ID、订户 ID、经办人 ID 等。

查询参数

参数	类型	必填	说明
orderId	string	是	CertCloud 订单 ID（下单接口响应的 data.id）

响应字段

certId 为空不是错误

当证书签发流程中云签标识尚未生成时，certId / subjectId / managerId / status 均返回空字符串，HTTP 状态码仍为 200。调用方应据 certId 是否为空判断是否已经可以调用 /esign/** 下的其余接口，而不是把空值当作异常处理。

字段	类型	说明
certId	string	云签证书 ID；标识未就绪时为空
subjectId	string	云签订户 ID：个人证书为订户本人 ID，企业证书为机构主体 ID（不可作为 signerId 使用，机构主体不能签字）
managerId	string	云签经办人 ID：企业证书专有；个人证书为空。此处的「经办人」是法定代表人与经办人的统称——证书登记的企业人员无论本人是法定代表人还是经办人，都统一以本字段引用
orderId	string	CertCloud 订单 ID（回显请求参数）
certificateId	string	CertCloud 证书 ID（下单响应 data.certificate.id）
status	string	证书派生状态，取值与查询证书状态一致；标识未就绪时为空

请求示例

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

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/certs?orderId=order-xxx', {
  headers: {
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  }
})

req, _ := http.NewRequest("GET", "https://api.certcloud.cn/openapi/v3/esign/certs?orderId=order-xxx", nil)
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
resp, _ := http.DefaultClient.Do(req)

import requests

resp = requests.get(
    'https://api.certcloud.cn/openapi/v3/esign/certs',
    params={'orderId': 'order-xxx'},
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    }
)

响应示例

200成功（云签标识已就绪）

{
  "code": "0",
  "data": {
    "certId": "esign-cert-xxx",
    "subjectId": "subject-xxx",
    "managerId": "manager-xxx",
    "orderId": "order-xxx",
    "certificateId": "cert-xxx",
    "status": "NORMAL"
  }
}

200成功（云签标识尚未就绪，非错误）

{
  "code": "0",
  "data": {
    "certId": "",
    "subjectId": "",
    "managerId": "",
    "orderId": "order-xxx",
    "certificateId": "cert-xxx",
    "status": ""
  }
}

错误码

HTTP 状态码	code	说明
400	esign_invalid_request	缺少 orderId 查询参数
404	esign_cert_not_found	该订单不存在云签标识映射
403	esign_cross_account_denied	订单不属于当前账户