文档中心

Appearance

撤销预授权 ​

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

发起对预授权的撤销意愿：接口返回 confirmUrl，需转发给证书归属的终端用户打开，由其在云签意愿页阅读授权范围、勾选废弃确认并完成核验。确认完成后，预授权才置为 REVOKED，剩余额度作废，对应 Token 同步失效，后续凭预授权 Token 签名将被拒绝。

撤销不是即时生效——须终端用户本人确认

本接口不直接撤销预授权，只创建一个撤销意愿（建单形态，与创建预授权意愿同构）。在终端用户于云签意愿页完成撤销确认之前，预授权仍为 ACTIVE，携 Token 签名不受影响。撤销结果经查询预授权状态观测：status=REVOKED 即撤销完成。

X-ES-Request-ID 必填

本接口为幂等创建类接口，请求头必须携带 X-ES-Request-ID 作为幂等键（口径同创建预授权意愿）。同一幂等键重试会复用首次发起的意愿，不会重复发起；同一幂等键携带不同的请求体重试会被上游终态拒绝（HTTP 409），须换新的 X-ES-Request-ID。

路径参数 ​

参数类型必填说明
grantIdstring是预授权 ID。首个入口是回调 + 主动查询双通道：预授权完成回调 esign:grant_ready（预授权生效时与 Token 一并送达）或查询意愿结果按创建预授权时的 willId 主动查询，首次凭预授权 Token 签名的响应中同样返回

Body 参数 ​

以下参数均为可选：

参数类型必填说明
willDescriptionstring否撤销告知文案（不超过 1000 字符），在云签意愿页向终端用户展示，说明为何废弃该预授权
reasonstring否撤销原因（不超过 256 字符），随撤销意愿进入存证与审计留痕
allowedModesarray否要求意愿页支持的核验方式，可选 SMS / TENCENT_SMART_WITNESS / TOTP / PIN。收紧语义（同创建预授权意愿）：显式传入时其中每一种方式都必须对该场景与人员实际可用，任一不可用则创建失败；不传表示按实际可用方式开放。空数组非法
successRedirectUrlstring否意愿完成后的跳转地址（原样透传云签）
endRedirectUrlstring否意愿流程结束后的跳转地址（原样透传云签）

响应字段 ​

响应形态与创建预授权意愿同构。

字段类型说明
willIdstring撤销意愿 ID。撤销进度可经查询意愿结果按本 ID 查询（含 businessStatus），或更简洁地以查询预授权状态的 status=REVOKED 为完成判据
confirmUrlstring转发给证书归属的终端用户打开、阅读授权范围并勾选废弃确认的一次性链接，规则同意愿模型说明（云签域名、原样透传、请勿缓存或记录日志）
confirmUrlExpireAtstring意愿确认链接（confirmUrl）的失效时间（毫秒时间戳字符串）。请在此之前转发给终端用户完成确认
expireAtstring意愿整体的过期时间（毫秒时间戳字符串，长整型一律字符串，见通用说明）。超过该时间后意愿转为过期终态
willStatusstring云签侧的真实意愿状态，创建成功后通常为待确认态 PENDING；取值见查询意愿结果。不代表撤销已完成——撤销进度以查询预授权状态返回的 status=REVOKED 为准

撤销意愿的观测与重复调用

  • 撤销意愿可经查询意愿结果按 willId 查询（与云签 B2 口径一致，含 willStatus 与 businessStatus）；更简洁的完成判据是查询预授权状态：status=REVOKED 即撤销完成。
  • 对已处于终态（REVOKED / EXPIRED / EXHAUSTED）的预授权调用本接口会被上游拒绝（409 esign_upstream_rejected）——云签不允许为非生效中的预授权创建撤销意愿（语义上已无需撤销）。
  • 同一 certId + signTaskId 下已存在未完成的撤销意愿时，重复创建会被拒绝（409 esign_upstream_rejected——按证书与签署任务判定，而非按单个额度）；请引导终端用户完成已有的 confirmUrl，或等其过期后再发起。

请求示例 ​

bash
curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-xxx/revoke' \
  -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: 8f2e4b6d-9a1c-4e3f-b5d7-0c2a4e6f8b1d' \
  -d '{
    "willDescription": "「采购合同批量签署」任务已终止，废弃剩余预授权额度"
  }'

响应示例 ​

200成功（返回撤销意愿）
json
{
  "code": "0",
  "data": {
    "willId": "will-xxx",
    "confirmUrl": "https://esign.example.com/wills/portal/eyJ0eXAiOiJKV1Qi",
    "expireAt": "1730000000000",
    "confirmUrlExpireAt": "1729913600000",
    "willStatus": "PENDING"
  }
}

错误码 ​

HTTP 状态码code说明
400esign_request_id_requiredX-ES-Request-ID 缺失，或其值不合规——去除首尾空白后必须非空、不超过 64 个字符，且只能由字母、数字、连字符 - 与下划线 _ 组成；空白、控制字符及其他符号（:、.、/、+、中文等）均非法
400esign_invalid_request请求参数非法（如 willDescription 超长、allowedModes 传空数组）
404esign_grant_not_found预授权不存在或不属于当前账户（grantId 有误）
409esign_upstream_rejected云签终态拒绝（如同一预授权已有未完成的撤销意愿、allowedModes 中存在不可用方式、同 X-ES-Request-ID 换请求体重试）；error 为 [上游码] 文案，仅供人工排查。见上游错误响应与重试
409esign_upstream_error云签暂时性失败；可使用相同 X-ES-Request-ID 稍后安全重试。见上游错误响应与重试