文档中心

Appearance

创建签署 PIN ​

POST
/openapi/v3/esign/pins

发起为证书关联人员创建签署 PIN（签署口令）的意愿。签署 PIN 是终端用户在云签意愿页可选的核验方式之一（也是预授权允许的核验方式之一）。接口返回 confirmUrl，需转发给该人员打开、完成身份核验后由本人在页面上设置 PIN 值，再通过查询意愿结果轮询生效结果。

PIN 值不经过 PIN 管理接口

创建意愿仅是预占动作，PIN 管理类接口均不接收 PIN 明文或摘要——PIN 值由用户本人在云签意愿页完成身份核验后自行设置，不经过 CertCloud 与调用方系统。唯一例外：首次 PIN 可在申请证书（下单）时经 esign_pin_digest 字段同步创建（值为 SHA-256(UTF-8(PIN)) 的 64 位小写十六进制摘要，见创建订单）；除此之外，任何接口都不接收 PIN 明文或摘要。

X-ES-Request-ID 必填

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

Body 参数 ​

参数类型必填说明
certIdstring是云签证书 ID，作为人员归属校验的锚点。要求证书状态为 NORMAL（见查询证书状态）——PIN 按「人员 × 证书」绑定；证书冻结 / 撤销期间不可操作，已过期同样会被拒（过期按证书有效期动态判定，状态可能仍显示 NORMAL），可通过证书标识映射查询获取
personTypestring是人员类型，可选 ENTERPRISE_PERSON（企业人员：经办人（含亲自经办的法定代表人）/ 委托人）/ PERSONAL_SUBSCRIBER（个人订户本人）
personIdstring是人员 ID。须是该证书下与 personType 相符的实际人员，按身份取值：个人订户本人取证书标识映射查询响应的 subjectId；企业经办人取同一响应的 managerId；委托人取新增委托人响应的 delegateId。获取方式见下方说明
allowedModesarray否要求意愿页支持的核验方式，可选 SMS / TENCENT_SMART_WITNESS / TOTP（PIN 类意愿不允许以 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 不匹配」三种成因， 排查时请用上述接口核对人员是否在册且启用。

响应字段 ​

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

生效的判定

本人在意愿页完成核验并设置 PIN 后（查询接口 willStatus=CONFIRMED），PIN 在云签侧异步生效。以查询意愿结果（willType=PIN_CREATE）返回的 businessStatus=SUCCEEDED 作为创建完成的判定依据（FAILED 时 failReason 给出原因）。

请求示例 ​

bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/pins' \
  -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: 3e8f1a2b-9c0d-4e5f-a6b7-c8d9e0f1a2b3' \
  -d '{
    "certId": "esign-cert-xxx",
    "personType": "ENTERPRISE_PERSON",
    "personId": "manager-xxx",
    "allowedModes": ["SMS"]
  }'

响应示例 ​

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当前请求被云签终态拒绝（如 allowedModes 中存在不可用方式）；error 为 [上游码] 文案，仅供人工排查、不可据其编程。见上游错误响应与重试
409esign_upstream_error云签暂时性失败；可使用相同 X-ES-Request-ID 稍后安全重试。见上游错误响应与重试