文档中心

Appearance

绑定动态口令（TOTP） ​

POST
/openapi/v3/esign/totp-bindings

发起为证书关联人员绑定动态口令（TOTP）的意愿。TOTP 绑定后可作为该人员在云签意愿页的核验方式之一（也是预授权允许的核验方式之一）。接口返回 confirmUrl，需转发给该人员打开、完成身份核验后由本人在页面上完成认证器绑定，再通过查询意愿结果（willType=TOTP_BIND）轮询生效结果。

TOTP 按人员绑定，certId 仅作归属校验

TOTP 绑定在人员（而非证书）维度生效。请求中的 certId 仅用于 CertCloud 侧的归属校验（确认该人员属于当前账户的证书），绑定关系本身与具体证书无关；TOTP 密钥等敏感信息全程不经过 API。

X-ES-Request-ID 必填

本接口为幂等创建类接口，请求头必须携带 X-ES-Request-ID 作为幂等键。同一幂等键重试会复用首次发起的意愿，不会重复发起。

Body 参数 ​

参数类型必填说明
certIdstring是云签证书 ID，作为人员归属校验的锚点，可通过证书标识映射查询获取
personTypestring是人员类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）/ 委托人）/ PERSONAL_SUBSCRIBER（个人订户本人）
personIdstring是人员 ID。须是该证书下与 personType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId；委托人取新增委托人响应的 delegateId。获取方式见下方说明
allowedModesarray否要求意愿页支持的核验方式，可选 SMS / TENCENT_SMART_WITNESS（绑定场景不允许以 TOTP 自证——尚未绑定）。收紧语义：显式传入时其中每一种方式都必须对该人员实际可用，任一不可用则创建失败；不传表示按实际可用方式开放

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、登记生效后才可用），但不校验其在该证书上的委托授权。

响应字段 ​

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

生效的判定

以查询意愿结果（willType=TOTP_BIND）返回的 businessStatus=SUCCEEDED 作为绑定完成的判定依据（FAILED 时 failReason 给出原因）；也可通过查询 TOTP 绑定状态确认当前绑定状态。

请求示例 ​

bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/totp-bindings' \
  -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: 7c2d5e6f-3a4b-4c5d-e8f9-a0b1c2d3e4f7' \
  -d '{
    "certId": "esign-cert-xxx",
    "personType": "ENTERPRISE_PERSON",
    "personId": "manager-xxx"
  }'

响应示例 ​

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_person_required缺少 personType 或 personId
400esign_invalid_body请求体非法：JSON 语法错误或字段类型不符（整数字段传字符串、字符串字段传数字等），请求体未被解析
400esign_invalid_request请求参数非法（如 certId 缺失）
404esign_cert_not_found证书不存在
403esign_cross_account_denied证书不属于当前账户
403esign_person_not_in_scope人员不在可用范围——personId 不存在或未启用，或与 personType 不匹配（本接口不校验委托授权）
409esign_idempotency_conflict复用同一 X-ES-Request-ID 但请求体与首次发起不一致；不回放旧意愿、也不创建新意愿，请改用新的 X-ES-Request-ID。见X-ES-Request-ID 幂等键
409esign_upstream_rejected当前请求被云签终态拒绝；error 为 [上游码] 文案，仅供人工排查、不可据其编程。典型场景：该人员已有生效中的绑定或已有绑定意愿在途（上游 -5080）——先经查询绑定状态确认，必要时先解绑。见上游错误响应与重试
409esign_upstream_error云签暂时性失败；可使用相同 X-ES-Request-ID 稍后安全重试。见上游错误响应与重试