忘记重置签署 PIN

POST

/openapi/v3/esign/pins/forgot

发起为证书关联人员忘记重置签署 PIN（签署口令）的意愿，适用于用户忘记 PIN 或 PIN 连续输错被锁定的场景。接口返回 confirmUrl，需转发给该人员打开、完成身份核验后由本人在页面上设置新 PIN 值，再通过查询意愿结果（willType=PIN_FORGOT）轮询生效结果。

生效时重置口令并解除锁定

PIN 连续输错导致的锁定不会自动解锁。本意愿生效（businessStatus=SUCCEEDED）时会重置口令并同时解除锁定，是被锁定用户的推荐恢复路径。

请求参数、响应形态、错误码与创建签署 PIN 完全一致（PIN 值不经过 API，由本人在意愿页设置；核验方式不允许以 PIN 自证——忘记场景下用户本就无法提供 PIN）。

X-ES-Request-ID 必填

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

Body 参数

参数	类型	必填	说明
certId	string	是	云签证书 ID，作为人员归属校验的锚点。要求证书状态为 NORMAL（见查询证书状态）——PIN 按「人员 × 证书」绑定；证书冻结 / 撤销期间不可操作，已过期同样会被拒（过期按证书有效期动态判定，状态可能仍显示 NORMAL）
personType	string	是	人员类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）/ 委托人）/ PERSONAL_SUBSCRIBER（个人订户本人）
personId	string	是	人员 ID。须是该证书下与 personType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId；委托人取新增委托人响应的 delegateId。获取方式见下方说明
allowedModes	array	否	要求意愿页支持的核验方式，可选 SMS / TENCENT_SMART_WITNESS / TOTP。收紧语义同创建签署 PIN

personId 如何获取

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

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

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

⚠️ 委托人须已生效：只有出现在查询企业人员结果中、 且 status=ENABLED 的人员才可用；委托人还须在该证书上持有当前生效的委托授权（ENABLED 人员在该证书上的授权可能已过期或不覆盖该证书）。新增委托人是双向意愿， 须授权主体与被委托人双方都确认、查询意愿结果返回 businessStatus=SUCCEEDED 后，云签才登记该人员。若意愿仍停在 PARTIAL_CONFIRMED （businessStatus=PENDING），说明尚有一方未确认、该委托人还未登记，此时传入其 delegateId 会返回 403 esign_person_not_in_scope。该错误码专指「人员不在本证书可用范围」， 与 esign_cross_account_denied（证书不属于当前账户）已分开，可据此程序化区分； 但它仍合并了「人员不存在」「委托未生效」「与 personType 不匹配」三种成因， 排查时请用上述接口核对人员是否在册且启用。

响应字段

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

生效判定同样以查询意愿结果返回的 businessStatus=SUCCEEDED 为准。

请求示例

curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/pins/forgot' \
  -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: 6b1c4d5e-2f3a-4b5c-d7e8-f9a0b1c2d3e6' \
  -d '{
    "certId": "esign-cert-xxx",
    "personType": "ENTERPRISE_PERSON",
    "personId": "manager-xxx"
  }'

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/pins/forgot', {
  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': '6b1c4d5e-2f3a-4b5c-d7e8-f9a0b1c2d3e6',
  },
  body: JSON.stringify({
    certId: 'esign-cert-xxx',
    personType: 'ENTERPRISE_PERSON',
    personId: 'manager-xxx',
  })
})

req, _ := http.NewRequest("POST", "https://api.certcloud.cn/openapi/v3/esign/pins/forgot", 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", "6b1c4d5e-2f3a-4b5c-d7e8-f9a0b1c2d3e6")
resp, _ := http.DefaultClient.Do(req)

import requests

resp = requests.post(
    'https://api.certcloud.cn/openapi/v3/esign/pins/forgot',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
        'X-ES-Request-ID': '6b1c4d5e-2f3a-4b5c-d7e8-f9a0b1c2d3e6',
    },
    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"
  }
}

错误码

本接口与创建签署 PIN 由同一处理逻辑承载，入口校验与上游错误映射完全一致，可能返回：

• 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 — 被云签终态拒绝（如 allowedModes 中存在对该人员不可用的方式）
• 409 esign_upstream_error — 云签暂时性失败，可用相同幂等键稍后重试

各项的完整含义、触发条件与处理建议见创建签署 PIN · 错误码，此处不重复维护。