云签电子签名认证证书

云签电子签名认证证书（eSign）接口，面向合作方提供基于 SM2 或 RSA 密钥的个人/机构电子签名认证证书云签能力：证书申请与托管、发起/查询/取消签名意愿、证书状态查询、私钥销毁、证书关联人员联系信息变更、企业证书的委托授权管理、意愿出证/存证素材获取。

与云签代理（vsign）不是同一个系统

本模块 esign 是电子签名认证证书云签平台的接入接口，与 vsign 云签代理（VSign 代码签名平台的透传代理）不是同一个系统，两者的证书类型、身份体系、术语均不通用，请勿混用。

通用说明

认证头部

所有 esign 接口均需要以下认证头部：

头部	类型	必填	说明
X-CC-Auth-Key	string	是	API 认证密钥
X-CC-Key-ID	string	是	API 密钥 ID

X-ES-Request-ID 幂等键

所有发起类写接口（发起签名意愿、销毁私钥、变更人员联系信息、创建预授权意愿、凭预授权 Token 签名、撤销预授权、创建/修改/清除/忘记重置签署 PIN、绑定/解绑动态口令、新增委托人、禁用委托人）都要求携带请求头 X-ES-Request-ID 作为幂等键：

• 同一 X-ES-Request-ID 重试会复用首次发起时的处理结果，不会重复创建意愿或重复下发指令。
• 建议使用 UUID 等全局唯一值，并在业务侧妥善保存以支持安全重试。
• 请求头值会先经规范化校验：去除首尾空白后必须非空、长度不超过 64 个字符，且只能由字母、数字、连字符 - 与下划线 _ 组成（即 [A-Za-z0-9_-]）。缺失、空串、仅空白、超长，或含空白、控制字符及其他符号（:、.、/、+、中文等），均返回 400 esign_request_id_required，不进入后续业务、也不调用云签。UUID 与 ULID 天然符合该规则，直接使用即可；若沿用业务侧单号作幂等键，请先确认其字符集。
• 意愿类写接口（发起签名、销毁私钥、变更人员联系信息，PIN、动态口令的创建 / 修改 / 清除 / 忘记重置 / 绑定 / 解绑，以及新增/禁用委托人）会额外校验请求体指纹：同一 X-ES-Request-ID 携带不同请求体重发，返回 409 esign_idempotency_conflict（不回放旧意愿、也不创建新意愿），须改用新的 X-ES-Request-ID。新增委托人额外还有专属的 409 esign_delegate_authorization_overlap（生效期重叠）与 409 esign_delegate_replay_unavailable（幂等回放窗口已过），详见该接口文档。
• 预授权相关接口（创建预授权意愿、凭预授权 Token 签名）的请求体幂等由云签上游负责。
• 例外：取消意愿不要求携带该请求头（不是幂等创建操作）；所有 GET 查询接口同样不要求。

响应格式

接口响应统一为 JSON 格式，包含以下字段：

字段	类型	说明
code	string	状态码，"0" 表示成功
data	object	业务数据，成功时返回
error	string	错误信息，code 非 "0" 时返回

长整型一律为字符串

expireAt、signedAt 等毫秒级时间戳字段，响应中一律以 字符串 形式返回（如 "1730000000000"），不要按数字类型解析。

请求体同理区分数字与字符串

请求体无法解析时（JSON 语法错误，或字段类型不符——最常见的是把整数字段加引号传成字符串，如 "grantCount": "20"），所有携带请求体的接口统一返回 400 esign_invalid_body。收到该错误码时请先核对请求体的 JSON 语法与各字段类型，与业务参数校验类的 esign_invalid_request（参数缺失、取值非法）无关。

上游错误响应与重试

发起签名、销毁私钥和变更人员联系信息时，云签业务错误的 error 字段使用 [上游码] 文案 格式：

{
  "code": "esign_upstream_rejected",
  "error": "[-6003] 待签哈希算法不支持",
  "data": null
}

HTTP 409 表示当前请求已被终态拒绝，不能原样重试。请修正输入或证书状态后，使用新的 X-ES-Request-ID 再发起。

{
  "code": "esign_upstream_error",
  "error": "[-5009] 短信验证码发送过于频繁",
  "data": null
}

HTTP 409 且 code 为 esign_upstream_error 表示暂时性失败（上游忙 / 处理中 / 服务暂不可用），可保留原请求内容并使用**相同的 X-ES-Request-ID**稍后安全重试。

注意：终态拒绝（esign_upstream_rejected）与暂时性失败（esign_upstream_error）同为 HTTP 409，能否重试必须依据响应 code 区分，不能只看 HTTP 状态码：esign_upstream_rejected 勿原样重试，esign_upstream_error 可稍后重试。上述负数码和文案只用于人工排查与工单沟通，不承诺稳定。

完整调用时序

从个人/机构 SM2 或 RSA 电子签名认证证书申请，到签名、销毁、人员变更及证书生命周期管理的完整调用顺序，请参阅云签电子签名认证证书完整调用时序。

该页面集中维护外部调用方需要实现的轮询与终态判定：订单 issued 后仍须等待云签证书状态为 NORMAL；签名须取得 willStatus=SIGNED、signStatus=SUCCESS 和 signatures；销毁与人员变更须等待 businessStatus=SUCCEEDED，不能停在 willStatus=CONFIRMED。

就绪条件

• 创建订单接口路径中的 {productId} 是产品 ID；创建成功后，订单详情路径中的 {orderId} 才是订单 ID，二者不可混用。
• 订单 issued 只表示 CA 签发完成；还须依次经证书标识映射查询取得 certId、经查询证书状态确认 NORMAL，才表示材料已在云签侧就绪。轮询继续条件只有一条——status === "PENDING_ISSUE" 且未返回 hostingFailed，其余一切取值（含 VOIDED 与未知值）一律停轮，按「不是 NORMAL 就继续轮」实现会死循环，详见查询证书状态 · 停轮公式。
• 发起任何操作前都应先查询证书状态。签名与签署 PIN 四操作要求证书为 NORMAL；变更人员联系信息不设证书状态前置（certId 仅作归属锚点，撤销后同样可以换号）。
• ⚠️ 销毁私钥要求证书已撤销（REVOKED）或已过期：对未过期的 NORMAL / FROZEN 态证书直接发起销毁会被云签终态拒绝（409 esign_upstream_rejected，[-5013] 意愿绑定证书不可用）。

写操作的语义

• 意愿类（发起签名、销毁私钥、变更人员联系信息、凭据管理、委托、预授权）：同步返回 confirmUrl，须终端用户确认；结果经查询意愿结果轮询，生效以 businessStatus=SUCCEEDED 为准。
• ⚠️ 销毁私钥的 reason 必填且非空白：缺失、空串或纯空格均被拒（409 esign_upstream_rejected 携 [-1002]、不创建意愿），最长 512 字符；reason 进入审计留痕，请传真实业务原因，勿用占位符或统一默认文案。
• 证书撤销 / 冻结 / 解冻不再提供独立接口（撤销经通用吊销证书入口发起，吊销确认后 CertCloud 自动同步云签）。

意愿（Will）模型说明

发起签名意愿、销毁私钥、变更人员联系信息、禁用委托人，以及凭据管理的六个意愿接口（签署 PIN 四操作、TOTP 绑定/解绑），都属于「发起意愿」类接口，共用同一套交互模型：

1. 调用发起接口，同步返回 willId、confirmUrl、expireAt（毫秒时间戳字符串）、willStatus。
2. 将 confirmUrl 转发给终端用户（证书归属的自然人）打开，由其完成人脸核验等意愿确认动作。

新增委托人是双向意愿，两条 confirmUrl

新增委托人是本模型的一个变体：单次调用返回一个 willId，但同时返回两条 confirmUrl（授权主体与被委托人各一条），两条链接同时有效、确认不限先后，须双方均确认才生效；轮询与生效判定方式与本节一致，仍按 willId 经查询意愿结果确认。其余细节见新增委托人文档。

confirmUrl 是云签侧的一次性短链

confirmUrl 由云签平台生成、CertCloud 原样透传，因此它的域名是云签的域名，不是 CertCloud 的。终端用户的浏览器会直连云签意愿页打开，不经过 CertCloud 转发。

• 链接带一次性令牌且有时效（见 expireAt），请勿缓存、勿记录到日志、勿在公开渠道传播，仅定向下发给该证书归属的自然人。
• 意愿已进入终态或已被取消时，发起接口返回的 confirmUrl 为空字符串。

3. 调用方通过 查询意愿结果 接口轮询意愿的最终结果：
   • willId 与查询参数 requestId（即发起时的 X-ES-Request-ID）二选一定位，两者不可同传也不可都不传；
   • 建议非终态时以 3–5 秒 间隔轮询、进入终态即停；并发预算与抖动要求见轮询预算与限流；
   • ⚠️ willStatus=CONFIRMED 不等于完成：销毁 / 人员变更 / 凭据 / 委托 / 预授权意愿在用户确认后由云侧异步生效，须以 businessStatus=SUCCEEDED 判定（FAILED 时 failReason 给出原因），详见查询意愿结果 · businessStatus 取值；
   • ⚠️ 只有签名（SIGN）意愿可以取消，且仅限终端用户尚未确认时——见取消意愿；其余类型及已确认的签名意愿均返回 409 esign_upstream_rejected，只能等待自然过期，或用对应业务手段（委托授权用禁用委托人，预授权用撤销预授权）；
   • ⚠️ 确认链接的失效时间是 confirmUrlExpireAt，不是 expireAt：expireAt 是意愿整体的过期时间，confirmUrlExpireAt 是确认链接的过期时间，后者恒早于或等于前者（它还受证书 / 密钥有效期约束）。按 expireAt 安排下发时机会出现「意愿还没过期、链接已经打不开」。目前仅创建预授权意愿与撤销预授权在响应中返回该字段，其余发起类接口暂未透出——请以「尽快转发、不要临期下发」为准。

预授权签署（两步调用）

除「每次签署都逐次确认意愿」的一步轨外，esign 还提供两步轨——预授权签署：

1. 第一步：创建预授权意愿，终端用户在云签意愿页一次性确认「授权覆盖本任务后续 N 次 / T 时间内的签名」，云签分配预授权额度并签发额度 Token（grantToken）。
2. 第二步：调用方携 Token 调用凭预授权 Token 签名，同步取得签名值——无需终端用户逐次确认，不设签名结果回调，也无需轮询意愿结果。

额度与有效期经查询预授权状态对账。需要提前作废时，经撤销预授权发起撤销意愿，由终端用户本人在云签意愿页确认后预授权才置 REVOKED、Token 同步失效。

signTaskId 是签署任务号，不是 CertCloud 订单号

预授权相关接口中的 signTaskId 是调用方业务侧的签署任务号（由调用方自行定义，第一步与第二步须保持一致），用于界定预授权额度的作用范围——同一 certId + signTaskId 至多存在一个生效中的预授权。它与创建订单/订单详情中的 CertCloud 订单 ID 不是同一概念，请勿混用。

⚠️ 2026-08-03 起该字段由 orderNo 更名为 signTaskId（不兼容变更，旧名不再接受）；orderNo 现专指 CertCloud 证书订单号。详见变更日志。

一步轨与两步轨并存，预授权不可用时回落一步轨

两条轨道长期并存、互不影响。预授权未开通、已过期、次数用尽或已撤销时，凭预授权 Token 签名返回 409 esign_upstream_rejected，此时应回落一步轨——改用发起签名意愿逐次确认完成签署；如需继续两步轨，重新创建预授权意愿即可。

grantId 与 Token 交付方式：回调加速，主动查询/拉取兜底

grantId 与 Token 受同一生效门控（businessStatus=SUCCEEDED）：预授权生效后经预授权完成回调 esign:grant_ready推送，或经查询意愿结果按创建预授权时的 willId 查询取得 grantId（不含 Token）。

Token 由云签经回调 + B2 查询双通道交付 CertCloud 并加密留存；调用方经领取预授权 Token按 grantId 拉取（可重复领取；刚生效时 Token 可能短暂在途，返回 409 esign_grant_token_not_available 时稍后重试）。Token 是敏感凭据（勿记录日志、勿拼入 URL、勿存入前端本地存储）且不是一次性凭据——同一 Token 可在授权窗口内反复用于签名，直至过期 / 撤销才失效；有限次数（usageLimitEnable=true）额度耗尽后也失效，不限次数（usageLimitEnable=false，2026-09-04 新增）不扣减次数、只受有效期约束。查询预授权状态、查询意愿结果与预授权完成回调恒返回 usageLimitEnable，不限次数时不返回 usageLimit / usageRemaining——请以这三处的 usageLimitEnable 判断模式，勿把次数字段缺失当作 0；凭预授权 Token 签名是签名接口，不返回 usageLimitEnable，仅有限次数返回 usageRemaining。

签名数据格式与验签

请求字段 dataHash 与响应字段 signature 的编码口径，对发起签名意愿（一步轨）与凭预授权 Token 签名（两步轨）完全一致。按本节口径提交与解析，调用方可脱离 CertCloud 与云签独立完成验签。

dataHash 提交口径

dataHash 是调用方在本地算出的摘要，十六进制小写字符串（SM3 / SHA-256 → 64 字符，SHA-384 → 96，SHA-512 → 128），算法须与本次请求的 hashAlg 一致。签名环节云签只接收摘要、不接触文件原文。

SM2 证书的 dataHash 不是裸 SM3(文件原文)

SM2 证书必须提交 GM/T 0003 定义的签名输入 e 值：

1. 按 GM/T 0009 计算 Z_A——输入为默认用户标识 1234567812345678、SM2 曲线参数与签名者证书公钥坐标；
2. e = SM3(Z_A ‖ 文件原文)，取其十六进制小写作为 dataHash 提交。

若直接提交 SM3(文件原文)，签名调用会正常成功，但得到的签名值事后用证书公钥验不过——错误不会在接口层暴露，只会在验签或出证环节才发现，请务必在联调阶段自验一次。

RSA 证书没有这一步：dataHash 就是 SHA256/384/512(文件原文)。

files 可携带多个元素，每个 dataHash 独立签名，响应 signatures[] 与提交顺序一一对应；fileName 仅用于展示与结果对应，不参与哈希绑定。

signature 编码格式

signature 为 Base64（RFC 4648，含填充）编码的原始签名值，内层格式随证书密钥算法：

证书算法	签名方案	signature 内层格式
RSA	RSASSA-PKCS1-v1_5（PKCS#1 v1.5，非 PSS；按 hashAlg 组 DigestInfo）	与密钥等长的签名值（RSA-2048 → 256 字节）
SM2	GM/T 0003 SM2 数字签名	ASN.1 DER 编码的 SEQUENCE { r INTEGER, s INTEGER }——不是 64 字节 r‖s 裸拼接（Base64 解码后首字节为 0x30 可据此识别）

调用方验签步骤

RSA：① 对文件原文按 hashAlg 计算摘要 → ② Base64 解码 signature → ③ 用签名证书公钥按 PKCS#1 v1.5 + 同一 hashAlg 验证（JCA SHA256withRSA，或 openssl dgst -sha256 -verify pubkey.pem -signature sig.bin data.bin）。

SM2：① 按 GM/T 0009 以默认用户标识 1234567812345678 与证书公钥计算 Z_A → ② e = SM3(Z_A ‖ 文件原文) → ③ Base64 解码 signature 得 DER，解析出 r、s（或直接使用支持 GM/T 0003 的库，如 BouncyCastle SM2Signer、各厂商国密 SDK）→ ④ 用证书公钥对 e 验证 (r, s)。

验签材料：签名证书与证书链由证书签发环节交付——证书签发回调 esign:cert_issued 直接携带 certPem / chainPem，或经获取订单详情取 certificate.pem；请随证书档案妥善保存。签名响应中的 certSerialNumber 用于确认本次签名所用证书与档案一致。销毁私钥只影响后续签名，历史签名在存证期内仍可复核。

凭据管理（签署 PIN / TOTP）

签署 PIN（签署口令）与动态口令（TOTP）是终端用户在云签意愿页可选的核验方式。以下接口用于以「发起意愿」模型管理这两类凭据（流程同意愿模型：返回 confirmUrl → 终端用户本人在页面完成核验与操作 → 经查询意愿结果轮询至 businessStatus=SUCCEEDED 才算生效）：

• 签署 PIN：创建、修改、清除、忘记重置（重置并解除锁定）。PIN 由用户本人在意愿页设置；唯一例外是首次 PIN 可在下单时经 esign_pin_digest 同步创建（见创建订单）。
• TOTP：绑定、解绑、查询绑定状态。TOTP 按人员绑定，certId 仅作归属校验锚点。

凭据锁定不会自动解锁

PIN 连续输错锁定后，恢复路径为忘记重置（重置并解锁）或清除后重新创建；TOTP 锁定的恢复路径为解绑后重新绑定。

allowedModes 为收紧语义

创建预授权意愿与凭据管理各意愿接口均支持可选的 allowedModes（要求意愿页支持的核验方式）。其语义是收紧而非偏好：显式传入时，其中每一种方式都必须对该场景与人员实际可用，任一不可用则创建失败（409 esign_upstream_rejected）；不传表示按实际可用方式开放。各接口允许的取值不同（如 PIN 类意愿禁止以 PIN 自证、TOTP 绑定禁止以 TOTP 自证），见各接口参数表。

签发说明

个人/机构、SM2/RSA 云签电子签名认证证书的签发均复用创建订单接口。下单时必须传 certificate.csr_from: "esign"，不得传 CSR 或私钥；云签负责生成并托管私钥、生成 CSR。完整字段要求和四类请求示例见创建订单文档。

下单成功后的调用顺序如下：

1. 保存创建响应中的订单 ID，经获取订单详情轮询至 issued（创建路径用产品 ID，详情路径用订单 ID）；
2. 经证书标识映射查询轮询取得云签侧 certId（同时保存 subjectId 与 managerId；映射未生成时该字段为空，继续轮询）；
3. 经查询证书状态轮询至 NORMAL——issued 不代表云签托管已完成，PENDING_ISSUE 时等待系统自动重试即可；
4. 状态为 NORMAL 后，才可发起签名或人员信息变更（销毁私钥的前置条件见上文「就绪条件」）。证书撤销经通用吊销证书入口发起，吊销确认后 CertCloud 自动同步云签；冻结/解冻能力不对外提供。

完整端到端流程和各阶段的停轮信号见云签电子签名认证证书完整调用时序。

接口列表

签名意愿

• 发起签名意愿
• 查询意愿结果
• 取消意愿
• 获取出证/存证素材

预授权签署（两步调用）

• 创建预授权意愿
• 凭预授权 Token 签名
• 查询预授权状态
• 领取预授权 Token
• 撤销预授权

凭据管理（签署 PIN / TOTP）

• 创建签署 PIN
• 修改签署 PIN
• 清除签署 PIN
• 忘记重置签署 PIN
• 绑定动态口令（TOTP）
• 解绑动态口令（TOTP）
• 查询 TOTP 绑定状态

证书标识与状态

• 证书标识映射查询
• 查询证书状态

密钥管理

• 销毁私钥（控制人意愿）

人员信息变更

• 变更人员联系信息

委托授权（仅企业证书）

• 新增委托人
• 禁用委托人
• 查询企业人员
• 查询委托授权记录