查询预授权状态

GET

/openapi/v3/esign/sign-grants/:grantId

查询预授权的额度、有效期与当前状态，用于额度对账，以及确认撤销预授权后的最终状态。

grantId 的来源

grantId 首个入口是回调 + 主动查询双通道：预授权生效后，经预授权完成回调 esign:grant_ready 主动推送，或经查询意愿结果按创建预授权时的 willId 主动查询取得（businessStatus=SUCCEEDED 后即可，不含 Token）；首次凭预授权 Token 签名成功后的响应中同样返回。在取得 grantId 之前，本接口无法定位该预授权。

路径参数

参数	类型	必填	说明
grantId	string	是	预授权 ID

响应字段

字段	类型	说明
grantId	string	预授权 ID
certId	string	云签证书 ID
certDn	string	证书主题可分辨名称（DN）
certLevel	string	证书等级：BASIC（基础级）/ HIGH（高等级）
signTaskId	string	签署任务号（调用方业务侧定义，见创建预授权意愿）
openedWillId	string	发起该预授权的意愿 ID
verificationMode	string	预授权意愿的实际核验方式——终端用户在意愿页完成授权时实际使用的方式：SMS / TENCENT_SMART_WITNESS / PIN / TOTP
usageLimitEnable	boolean	次数模式（2026-09-04 新增，恒返回）：true 有限次数、false 不限次数。历史预授权均为 true
usageLimit	string	授权总次数（长整型一律字符串）。仅有限次数返回，不限次数缺省
usageRemaining	string	剩余可用次数。仅有限次数返回，不限次数缺省——勿把缺失当作 0
validFrom	string	生效时间（毫秒时间戳字符串）
validUntil	string	失效时间（毫秒时间戳字符串）。不限次数同样受其约束
lastUsedAt	string	最近一次凭预授权 Token 签名的时间（毫秒时间戳字符串）；从未使用过时该字段缺省；不限次数额度不更新该字段（始终缺省）
status	string	预授权状态，见下表

status 取值

取值	说明
ACTIVE	生效中，可携 Token 签名
EXHAUSTED	次数已用尽（终态）。仅有限次数可达，不限次数不会进入此状态
EXPIRED	已过期（终态）
REVOKED	已撤销（终态）

进入任一终态后，对应 Token 同步失效。如需继续使用两步轨，重新创建预授权意愿；或回落一步轨发起签名意愿。

请求示例

curl -X GET 'https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-xxx' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-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/sign-grants/grant-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)

import requests

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

响应示例

200成功

{
  "code": "0",
  "data": {
    "grantId": "grant-xxx",
    "certId": "esign-cert-xxx",
    "certDn": "CN=张三,O=某某科技有限公司,C=CN",
    "certLevel": "HIGH",
    "signTaskId": "task-20260721-001",
    "openedWillId": "will-xxx",
    "verificationMode": "SMS",
    "usageLimitEnable": true,
    "usageLimit": "10",
    "usageRemaining": "6",
    "validFrom": "1730000000000",
    "validUntil": "1730259200000",
    "lastUsedAt": "1730001200000",
    "status": "ACTIVE"
  }
}

错误码

HTTP 状态码	code	说明
404	esign_grant_not_found	预授权不存在、不属于当前账户，或 grantId 尚未经任一通道（回调 / 查询意愿结果 主动查询 / 首次携 Token 签名）取得而无效
409	esign_upstream_rejected	云签终态拒绝；error 为 [上游码] 文案，仅供人工排查。见上游错误响应与重试
409	esign_upstream_error	云签暂时性失败，可稍后重试。见上游错误响应与重试