解绑动态口令（TOTP）

POST

/openapi/v3/esign/totp-bindings/unbind

发起为证书关联人员解绑动态口令（TOTP）的意愿。接口返回 confirmUrl，需转发给该人员打开、完成身份核验确认解绑，再通过查询意愿结果（willType=TOTP_UNBIND）轮询生效结果。TOTP 异常（如认证器丢失、被锁定）时，恢复路径即为解绑后重新绑定。

请求参数、响应形态、错误码与绑定动态口令（TOTP） 基本一致，差异仅在 allowedModes 允许的取值（解绑可用待解绑的 TOTP 自证）。

X-ES-Request-ID 必填

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

Body 参数

参数	类型	必填	说明
certId	string	是	云签证书 ID，作为人员归属校验的锚点
personType	string	是	人员类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）/ 委托人）/ PERSONAL_SUBSCRIBER（个人订户本人）
personId	string	是	人员 ID。须是该证书下与 personType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId；委托人取新增委托人响应的 delegateId。获取方式见下方说明
allowedModes	array	否	要求意愿页支持的核验方式，可选 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、登记生效后才可用），但不校验其在该证书上的委托授权。

响应字段

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

生效判定以查询意愿结果返回的 businessStatus=SUCCEEDED 为准；也可通过查询 TOTP 绑定状态确认解绑后的状态。

请求示例

curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/totp-bindings/unbind' \
  -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: 8d3e6f7a-4b5c-4d5e-f9a0-b1c2d3e4f5a8' \
  -d '{
    "certId": "esign-cert-xxx",
    "personType": "ENTERPRISE_PERSON",
    "personId": "manager-xxx"
  }'

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/totp-bindings/unbind', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
    'X-ES-Request-ID': '8d3e6f7a-4b5c-4d5e-f9a0-b1c2d3e4f5a8',
  },
  body: JSON.stringify({
    certId: 'esign-cert-xxx',
    personType: 'ENTERPRISE_PERSON',
    personId: 'manager-xxx',
  })
})

req, _ := http.NewRequest("POST", "https://api.certcloud.cn/openapi/v3/esign/totp-bindings/unbind", strings.NewReader(`{
  "certId": "esign-cert-xxx",
  "personType": "ENTERPRISE_PERSON",
  "personId": "manager-xxx"
}`))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
req.Header.Set("X-ES-Request-ID", "8d3e6f7a-4b5c-4d5e-f9a0-b1c2d3e4f5a8")
resp, _ := http.DefaultClient.Do(req)

import requests

resp = requests.post(
    'https://api.certcloud.cn/openapi/v3/esign/totp-bindings/unbind',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
        'X-ES-Request-ID': '8d3e6f7a-4b5c-4d5e-f9a0-b1c2d3e4f5a8',
    },
    json={
        'certId': 'esign-cert-xxx',
        'personType': 'ENTERPRISE_PERSON',
        'personId': 'manager-xxx',
    }
)

响应示例

200成功

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

错误码

本接口与绑定动态口令（TOTP） 由同一处理逻辑承载，入口校验与上游错误映射完全一致，可能返回：

• 400 esign_request_id_required — X-ES-Request-ID 缺失，或值超 64 字符 / 含 [A-Za-z0-9_-] 以外的字符
• 400 esign_person_required — 缺少 personType 或 personId
• 400 esign_invalid_body — 请求体非法：JSON 语法错误或字段类型不符（整数字段传字符串等），请求体未被解析
• 400 esign_invalid_request — 请求参数非法（如 certId 缺失）
• 404 esign_cert_not_found — 证书不存在
• 403 esign_cross_account_denied — 证书不属于当前账户
• 403 esign_person_not_in_scope — 人员不在可用范围——personId 不存在或未启用，或与 personType 不匹配（本接口不校验委托授权）
• 409 esign_idempotency_conflict — 复用同一 X-ES-Request-ID 但请求体不一致，须换新幂等键
• 409 esign_upstream_rejected — 当前请求被云签终态拒绝，error 为 [上游码] 文案。典型场景：当前无可用绑定（未绑定或绑定尚未首码激活，上游 -5067）；同一人员有绑定/解绑操作在途（上游 -5044）
• 409 esign_upstream_rejected — 被云签终态拒绝（如 allowedModes 中存在对该人员不可用的方式）
• 409 esign_upstream_error — 云签暂时性失败，可用相同幂等键稍后重试

各项的完整含义、触发条件与处理建议见绑定动态口令（TOTP）· 错误码，此处不重复维护。