取消意愿

POST

/openapi/v3/esign/wills/:willId/cancel

取消一个尚未完成的签名 / 销毁 / 人员变更意愿。

适用范围：仅签名意愿、仅待确认态

① 意愿类型——当前只有 willType=SIGN 的签名意愿可取消。销毁私钥、变更人员联系信息、创建/撤销预授权、签署 PIN 与 TOTP 的六类凭据意愿、新增/禁用委托人——这些意愿都不支持取消，调用本接口会被云签拒绝（409 esign_upstream_rejected，上游码 [-5005]）。

② 意愿状态——只有仍处于 PENDING（等待终端用户确认）的意愿可以取消。终端用户一旦完成意愿确认，授权即视为成立，此后 CONFIRMED / SIGNING / SIGNED 一律不可取消（同为 [-5005]）。这是刻意的防竞态设计：不允许事后砍掉已获授权的签名。此时签名会照常完成，结果仍经查询意愿结果获取，请在业务侧自行处置。

③ 已是终态（CANCELLED / EXPIRED / FAILED）时重复取消幂等返回成功，不改写状态，响应回带库内当前状态。

不支持取消的意愿如需终止，请改用对应的业务手段：委托授权用禁用委托人，预授权用撤销预授权；其余类型只能等待其自然过期（意愿默认有效期 3 天）。

无需 X-ES-Request-ID

取消操作不是幂等创建操作，无需携带 X-ES-Request-ID 请求头。

响应中的 willStatus 非最终真实状态

本接口成功返回 HTTP 202，表示取消请求已被受理（accepted: true），响应中的 willStatus 是受理时刻的当前实际状态，不代表云签侧已确认的最终终态。取消是否真正生效（CANCELLED）需要通过查询意愿结果接口轮询确认。

⚠️ 202 只表示 CertCloud 已受理并向云签转发。云签侧拒绝取消时（非 SIGN 类型，或意愿已确认 / 签名中 / 已完成）返回 409 esign_upstream_rejected（上游码 [-5005]），意愿状态不会发生变化——202 受理与 409 拒绝分别对应可取消与不可取消两类情形，切勿把 202 当作取消成功的判据。

路径参数

参数	类型	必填	说明
willId	string	是	意愿 ID

Body 参数

参数	类型	必填	说明
reason	string	是	取消原因（如「订单取消」「文件变更」），进入意愿记录留痕。云签侧为必填，缺失或传空串会被按非法参数拒绝（上游码 -1002）

响应字段

字段	类型	说明
willId	string	被取消的意愿 ID（回显路径参数）
willStatus	string	受理时刻的意愿状态，取值见查询意愿结果。不是取消后的终态，见上方说明
accepted	boolean	取消请求已受理，恒为 true（未受理时以错误码返回，不会出现 false）

本接口不返回 confirmUrl

取消意愿无需终端用户确认，响应中不含 confirmUrl / expireAt —— 这与其余建单类接口（发起签名意愿等）不同。

请求示例

curl -X POST 'https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx/cancel' \
  -H 'Content-Type: application/json' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id' \
  -d '{
    "reason": "业务取消"
  }'

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx/cancel', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  },
  body: JSON.stringify({ reason: '业务取消' })
})

req, _ := http.NewRequest("POST", "https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx/cancel", strings.NewReader(`{
  "reason": "业务取消"
}`))
req.Header.Set("Content-Type", "application/json")
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.post(
    'https://api.certcloud.cn/openapi/v3/esign/wills/will-xxx/cancel',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    },
    json={'reason': '业务取消'}
)

响应示例

202已受理

{
  "code": "0",
  "data": {
    "willId": "will-xxx",
    "willStatus": "PENDING",
    "accepted": true
  }
}

错误码

HTTP 状态码	code	说明
404	esign_will_not_found	意愿不存在，或不属于当前账户