文档中心

Appearance

查询 TOTP 绑定状态 ​

GET
/openapi/v3/esign/totp-bindings/status

查询证书关联人员当前的动态口令（TOTP）绑定状态，可用于确认绑定/解绑意愿生效后的最终状态，或在发起绑定前检查是否已绑定。

查询参数 ​

参数类型必填说明
certIdstring是云签证书 ID，作为人员归属校验的锚点
personTypestring是人员类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）/ 委托人）/ PERSONAL_SUBSCRIBER（个人订户本人）
personIdstring是人员 ID。须是该证书下与 personType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId；委托人取新增委托人响应的 delegateId。获取方式见下方说明

personId 如何获取

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

  1. 用下单响应中拿到的 CertCloud 订单 ID（data.id）调用证书标识映射查询：GET /openapi/v3/esign/certs?orderId=<订单 ID>。
  2. 按本请求所指人员的实际身份，取对应字段作为 personId：
    • 个人订户本人（personType=PERSONAL_SUBSCRIBER）→ 取映射响应的 subjectId
    • 企业经办人（personType=ENTERPRISE_PERSON）→ 取映射响应的 managerId
    • 委托人（personType=ENTERPRISE_PERSON）→ 取新增委托人响应的 delegateId（该字段不在映射响应中，无需第 1 步）。若手上没有当初的建单响应（例如该委托人由他人早先登记），可改用查询企业人员按 certId 反查：响应中 personType=DELEGATE 的条目，其 personId 即为所需值

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

⚠️ TOTP 不校验委托授权：TOTP 按人员维度绑定、不依赖具体证书（certId 仅由 CertCloud 用作归属校验锚点）——委托人同样须人员状态为 ENABLED（新增委托意愿未生效时该人员建档为 DISABLED、登记生效后才可用），但不校验其在该证书上的委托授权。

响应字段 ​

字段类型说明
statusstring绑定状态，见下表
activatedAtstring激活时间（毫秒时间戳字符串）；未激活时该字段缺省
lockedUntilstring预留字段（毫秒时间戳字符串）。当前锁定策略为永久锁定（连续核验失败达到上限后锁定，解绑后重新绑定恢复），该字段通常缺省，调用方无需依赖

status 取值 ​

取值说明
AVAILABLE已绑定且可用
NOT_CONFIGURED未绑定
PENDING绑定进行中（绑定意愿已发起、尚未完成首码激活）
LOCKED已锁定（连续核验失败达到上限）。永久锁定、不会自动解锁，恢复路径为解绑后重新绑定
DISABLED已停用（云签侧停用该凭据，恢复前不可用）

不返回敏感信息

本接口不返回 TOTP 密钥、算法参数、计数器或错误次数等敏感信息。

请求示例 ​

bash
curl -X GET 'https://api.certcloud.cn/openapi/v3/esign/totp-bindings/status?certId=esign-cert-xxx&personType=ENTERPRISE_PERSON&personId=manager-xxx' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

响应示例 ​

200成功
json
{
  "code": "0",
  "data": {
    "status": "AVAILABLE",
    "activatedAt": "1730000000000"
  }
}

错误码 ​

HTTP 状态码code说明
400esign_person_required缺少 personType 或 personId
400esign_invalid_request请求参数非法（如 certId 缺失）
404esign_cert_not_found证书不存在
403esign_cross_account_denied证书不属于当前账户
403esign_person_not_in_scope人员不在可用范围——personId 不存在或未启用，或与 personType 不匹配（本接口不校验委托授权）
409esign_upstream_error云签暂时性失败，可稍后重试。见上游错误响应与重试