查询意愿结果

GET

/openapi/v3/esign/wills/:willId

GET

/openapi/v3/esign/wills

查询签名意愿 / 销毁意愿 / 人员变更意愿 / 凭据管理意愿（签署 PIN 四操作、TOTP 绑定/解绑）/ 预授权意愿（SIGN_GRANT_OPEN）的当前状态与结果。支持通过路径参数 willId，或通过查询参数 requestId（发起时携带的 X-ES-Request-ID）二选一定位。

预授权意愿（SIGN_GRANT_OPEN）可查询 signTaskId 与 grantId

创建预授权意愿产生的意愿可通过本接口按 willId 查询：businessStatus=SUCCEEDED（预授权生效）后返回 grantId 与 usageLimitEnable / usageLimit / usageRemaining / validUntil（不限次数不含两个次数字段；长整型一律字符串，见通用说明），示例见下方响应示例。不返回 Token——Token 仍只经预授权完成回调 esign:grant_ready 或领取预授权 Token取得，grantId 首个入口由此升级为回调 + 本接口主动查询双通道，见预授权签署说明。businessStatus 未到 SUCCEEDED 时响应不含 grantId，按 businessStatus 继续轮询（判据同下方 businessStatus 取值）。额度实时明细以查询预授权状态为准，本接口返回的是查询时点的快照。⚠️ 预授权意愿仅支持按路径参数 willId 查询，不支持按 requestId + willType 查询（willType 查询参数的可选值不含 SIGN_GRANT_OPEN，见下方查询参数）。

撤销预授权产生的意愿不适用本接口

撤销预授权发起的撤销意愿（区别于上面按 willId 可查的预授权创建意愿）不能通过本接口查询，撤销进度以查询预授权状态（status=REVOKED 即撤销完成）为准。

willId 与 requestId 二选一

两者必须恰好提供一个：都提供或都不提供，均返回 esign_invalid_request。

轮询建议

意愿处于非终态时，建议以 3–5 秒的间隔轮询本接口。停止轮询的判据按意愿类型不同：

SIGN：willStatus 进入 SIGNED / FAILED / CANCELLED / EXPIRED，或 signStatus 进入 SUCCESS / FAILED / CANCELLED / EXPIRED。
KEY_DESTROY / PERSONNEL_UPDATE、凭据管理六类型（PIN_CREATE / PIN_UPDATE / PIN_CLEAR / PIN_FORGOT / TOTP_BIND / TOTP_UNBIND）及预授权 SIGN_GRANT_OPEN：businessStatus 进入 SUCCEEDED / FAILED，或 willStatus 进入 FAILED / CANCELLED / EXPIRED。注意 willStatus=CONFIRMED 不是停轮信号——确认后业务在云签侧异步生效，期间应继续轮询（见下方 businessStatus 取值）。预授权 businessStatus=SUCCEEDED 后响应带 grantId，即可停轮转入领取 Token / 携 Token 签名流程。

路径参数

参数	类型	必填	说明
willId	string	否	意愿 ID。与 `requestId` 二选一

查询参数

参数	类型	必填	说明
requestId	string	否	发起意愿时携带的 `X-ES-Request-ID`。与路径参数 `willId` 二选一
willType	string	否	意愿类型，配合 `requestId` 定位使用，可选 `SIGN` / `KEY_DESTROY` / `PERSONNEL_UPDATE` / `PIN_CREATE` / `PIN_UPDATE` / `PIN_CLEAR` / `PIN_FORGOT` / `TOTP_BIND` / `TOTP_UNBIND` / `DELEGATE_CREATE` / `DELEGATE_DISABLE`；缺省时仅按 `requestId` 匹配，若同一 `X-ES-Request-ID` 曾用于不同意愿类型可能匹配到非预期的一条，建议按发起时的类型显式传入

响应字段

本接口的响应由两部分拼合：前三个字段由 CertCloud 权威给出、恒定返回；其余字段来自云签的结果快照，随意愿类型与所处阶段出现或缺省。快照字段随云签演进，下表不是完整清单，请按需取用、不要假设未列出的字段不存在。

字段	类型	说明
willId	string	意愿 ID。恒定返回
willStatus	string	意愿状态，取值见下表。恒定返回
signStatus	string	签名状态，仅对 `SIGN` 类型意愿有意义。恒定返回（非签名类意愿为空字符串），取值见下方说明
willType	string	意愿类型。仅预授权意愿返回，恒为 `SIGN_GRANT_OPEN`；其余类型响应不含此字段
signId	string	签名记录 ID（签名类意愿，签名完成时出现）
certSerialNumber	string	签名所用证书序列号（签名类意愿）
signatures	array	逐文件签名结果，元素含 `fileName` / `dataHash` / `signature`（Base64），形态同凭预授权 Token 签名（签名类意愿）
signedAt	string	签名时间（毫秒时间戳字符串）。仅签名场景返回
tsToken	string	签名时间戳凭据：将本批签名结果与云签侧记录的签名时间绑定，供存证留存。按不透明字符串处理，签名完成时间以 `signedAt` 为准。仅签名成功后返回
businessStatus	string	业务生效状态，`SUCCEEDED` / `FAILED`。非签名类意愿据此判定业务是否真正生效
businessCompletedAt	string	业务完成时间（毫秒时间戳字符串，非签名类意愿）
failReason	string	失败原因，`businessStatus=FAILED` 或签名失败时出现
signTaskId	string	签署任务号（预授权意愿）。不依赖额度是否生效，待确认 / 成功 / 失败均返回
grantId	string	预授权 ID（预授权意愿，`businessStatus=SUCCEEDED` 后出现）
usageLimitEnable	boolean	次数模式（预授权意愿，2026-09-04 新增，与 `grantId` 同时出现）：`true` 有限次数、`false` 不限次数。历史预授权均为 `true`
usageLimit	string	授权总次数（预授权意愿，生效后出现；长整型一律字符串）。仅有限次数返回
usageRemaining	string	剩余可用次数（预授权意愿，生效后出现）。仅有限次数返回，不限次数缺省——勿把缺失当作 0
validUntil	string	预授权失效时间（毫秒时间戳字符串，预授权意愿，生效后出现）
source	string	授权窗口来源（预授权意愿，2026-08-07 新增）：`API`＝创建预授权意愿时由调用方参数指定、`DEFAULT`＝取云签平台默认配置、`PORTAL`＝多次预授权由终端用户在意愿页设置、`CSR`＝经审核链接预授权在同步签发时建立（2026-09-04 新增）。历史意愿不回填，缺失时无该字段

本接口不返回预授权 Token

预授权意愿即使 businessStatus=SUCCEEDED，响应中也不含 Token。Token 走预授权完成回调 esign:grant_ready 或领取预授权 Token。

上表几个字段的补充语义

signStatus 可选值 PENDING / SIGNING / SUCCESS / FAILED / CANCELLED / EXPIRED（后四者为终态；EXPIRED 表示意愿过期、待执行的签名记录同步失效）。非签名类意愿（KEY_DESTROY / PERSONNEL_UPDATE、凭据管理六类型及预授权 SIGN_GRANT_OPEN）该字段为空字符串。

participants[]（多方意愿，如新增委托人）每个参与人一条，含 participantId、participantRole（SIGNER / GRANTOR / DELEGATE / SELF）、status、verificationMode、confirmedAt，以及该参与人的 confirmUrl 与 confirmUrlExpireAt。这是判断「哪一方还没确认」的唯一途径——顶层 willStatus=PARTIAL_CONFIRMED 只说明「有人已确认」，不指明是哪一方。注意 confirmUrl 不随意愿状态或有效期隐藏，勿据其存在与否判断链接是否仍可用。

signatures[] 与请求 files[] 顺序一一对应，dataHash 原样回显（SM2 为提交时的 e 值）；signature 是 Base64 原始签名值——SM2 为 ASN.1 DER SEQUENCE { r, s }（非 64 字节裸拼接）、RSA 为 PKCS#1 v1.5，解析与验签见签名数据格式与验签。

签名类与非签名类的字段互斥：非签名类意愿不含 signId / signatures 等签名类字段，其完成时间以 businessCompletedAt 为准而非 signedAt。

signTaskId 比 grantId 更早可见：预授权意愿的 signTaskId 不依赖额度是否生效，待确认 / 成功 / 失败状态均返回，可在预授权尚未生效时就把该意愿与您系统内的签署任务对上账；而 grantId / usageLimitEnable / usageLimit / usageRemaining / validUntil 须 businessStatus=SUCCEEDED 后才出现（不限次数不含两个次数字段），此时不含 businessCompletedAt / failReason。

willStatus 取值

取值	说明
`PENDING`	等待终端用户确认
`PARTIAL_CONFIRMED`	部分确认（多方签署场景）
`CONFIRMED`	已确认——终端用户完成意愿确认。对 `SIGN` 是中间态；对 `KEY_DESTROY` / `PERSONNEL_UPDATE`、凭据管理六类型及预授权 `SIGN_GRANT_OPEN` 不等同于业务已生效（对预授权即不等同于已拿到 `grantId`），业务是否真正完成以 `businessStatus` 为准（见下）
`SIGNING`	签名中
`SIGNED`	已签名（`SIGN` 类型成功终态）
`FAILED`	失败（终态；含确认后业务生效失败的情形，原因见 `failReason`）
`CANCELLED`	已取消（终态）
`EXPIRED`	已过期（终态）

businessStatus 取值

仅对非签名类意愿（KEY_DESTROY / PERSONNEL_UPDATE、凭据管理六类型 PIN_CREATE / PIN_UPDATE / PIN_CLEAR / PIN_FORGOT / TOTP_BIND / TOTP_UNBIND 及预授权 SIGN_GRANT_OPEN）有意义：终端用户确认（willStatus=CONFIRMED）后，销毁 / 联系方式变更 / 凭据操作 / 预授权在云签侧异步生效，businessStatus 表达生效进度与结果（对预授权，SUCCEEDED 即代表 grantId 已可用，完成时间不透出，无 businessCompletedAt）。

取值	说明
`PENDING`	已确认，业务生效尚未开始
`PROCESSING`	业务生效中
`SUCCEEDED`	业务已生效（成功终态；完成时间见 `businessCompletedAt`；预授权 `SIGN_GRANT_OPEN` 无此字段，改带 `grantId` 与额度）
`FAILED`	业务生效失败（失败终态；原因见 `failReason`，此后 `willStatus` 亦转为 `FAILED`）
`NOT_APPLICABLE`	不适用（`SIGN` 类型意愿；该字段也可能直接缺失）

判定成功的唯一依据

KEY_DESTROY / PERSONNEL_UPDATE、凭据管理六类型及预授权 SIGN_GRANT_OPEN 意愿均以 businessStatus=SUCCEEDED 作为业务完成（预授权即 grantId 已可用）的判定依据，不要以 willStatus=CONFIRMED 判定销毁 / 变更 / 凭据操作 / 预授权已完成。兼容口径（KEY_DESTROY / PERSONNEL_UPDATE 及凭据管理六类型适用）：若响应中没有 businessStatus 字段且 willStatus=CONFIRMED（上游旧版本），则按已生效处理；预授权 SIGN_GRANT_OPEN 无此历史包袱，一律以 businessStatus=SUCCEEDED + grantId 非空为准。

可能出现的内部过渡态

除上述云签侧枚举外，willStatus 还可能返回 CertCloud 内部态（不属于云签平台语义，出现频率极低），三者处置方式不同：

CREATING：意愿创建中、尚未拿到云签 willId——继续轮询即可，通常数秒内转为 PENDING。
CREATE_FAILED：创建阶段即失败——仅轮询不会脱离该状态。以相同 X-ES-Request-ID 重新调用创建接口会复位并重试创建（幂等键复用同一意愿记录，不会重复发起）；重试前请先排查失败原因（如证书状态、签署人无效）。
RECONCILE_REQUIRED：持续查询异常超出重试宽限期，已停止自动轮询、等待后台核对——无需继续轮询，长时间未恢复请联系技术支持。

请求示例

bash

# 方式一：按 willId 查询
curl -X GET 'https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

# 方式二：按 requestId 查询
curl -X GET 'https://api.certcloud.cn/openapi/v3/esign/wills?requestId=8f14e45f-ceea-4d1a-9a0c-6f6a3b1f0a11&willType=SIGN' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

javascript

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx', {
  headers: {
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  }
})

req, _ := http.NewRequest("GET", "https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx", nil)
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
resp, _ := http.DefaultClient.Do(req)

python

import requests

resp = requests.get(
    'https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    }
)

响应示例

200成功（SIGN 类型意愿，已完成签名）

json

{
  "code": "0",
  "data": {
    "willId": "will-xxx",
    "willStatus": "SIGNED",
    "signStatus": "SUCCESS",
    "signId": "sign-xxx",
    "certSerialNumber": "0A1B2C3D",
    "signatures": [
      {
        "fileName": "contract.pdf",
        "dataHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
        "signature": "MEUCIQDx...(Base64)"
      }
    ],
    "signedAt": "1730000000000",
    "tsToken": "INTERNAL_TSA_V1:eyJ2ZXJzaW9uIjoiSU5URVJOQUxfVFNBX1YxIiwi...(Base64URL)"
  }
}

200成功（KEY_DESTROY 类型意愿，业务已生效）

json

{
  "code": "0",
  "data": {
    "willId": "will-yyy",
    "willStatus": "CONFIRMED",
    "signStatus": "",
    "businessStatus": "SUCCEEDED",
    "businessCompletedAt": "1730000000000"
  }
}

200成功（预授权意愿 SIGN_GRANT_OPEN，已生效）

json

{
  "code": "0",
  "data": {
    "willId": "will-zzz",
    "willType": "SIGN_GRANT_OPEN",
    "willStatus": "CONFIRMED",
    "signStatus": "",
    "businessStatus": "SUCCEEDED",
    "signTaskId": "task-20260721-001",
    "grantId": "grant-xxx",
    "usageLimitEnable": true,
    "usageLimit": "100",
    "usageRemaining": "100",
    "validUntil": "1730000000000",
    "source": "API"
  }
}

错误码

HTTP 状态码	code	说明
400	`esign_invalid_request`	`willId` 与 `requestId` 未恰好提供一个
403	`esign_cross_account_denied`	意愿不属于当前账户
404	`esign_will_not_found`	意愿不存在，或不属于当前账户——两种情形合并返回同一错误，不可区分，防止枚举他人 `willId`
409	`esign_upstream_rejected`	云签终态拒绝该查询；`error` 为 `[上游码] 文案`，仅供人工排查、不可据其编程
409	`esign_upstream_error`	云签暂时性失败，可原样稍后重试——本接口是纯查询、无幂等键，重试不产生副作用

业务流程

订单管理

ACME

证书管理

电子签名服务

审核链接

签名意愿

预授权签署（两步调用）

凭据管理（签署 PIN / TOTP）

证书标识与状态

密钥管理

人员信息变更

委托授权（仅企业证书）

组织管理

域名管理

账户设置

查询意愿结果

路径参数

查询参数

响应字段

willStatus 取值

businessStatus 取值

请求示例

响应示例

错误码

订单管理

ACME

证书管理

组织管理

域名管理

查询意愿结果 ​

路径参数 ​

查询参数 ​

响应字段 ​

willStatus 取值 ​

businessStatus 取值 ​

请求示例 ​

响应示例 ​

错误码 ​

查询意愿结果

路径参数

查询参数

响应字段

willStatus 取值

businessStatus 取值

请求示例

响应示例

错误码