撤销签署文档

POST /open/documents/revoke 天然资源级幂等

将一份未终结的签署文档强制置为作废终态(voided),并立即撤销其所有当前有效的签署方链接。

撤销效果与幂等保证
文档撤销后不可逆转恢复。一旦执行成功,所有签署人打开签署链接时均会提示“该文档已被发起人撤销”。本接口具备天然状态幂等特性,重复撤销同一已撤销文档不会报错,响应中的 already_revoked 会标识为 true

请求头 (Request Headers)

本接口无特殊请求头,仅需携带标准公共请求头(无需 Idempotency-Key)。详细标头定义与 HMAC-SHA256 签名算法请参阅:公共请求头与验签规范

请求体参数 (Request Body)

参数名 类型 必填 详细描述
document_id string 必填 需要撤销的目标文档唯一 UUID。
reason string 可选 撤销原因说明,最多 500 个字符。该内容将记录至平台的审计存证事件流中。

请求示例 (Request Example)

curl -X POST "https://api.example.com/open/documents/revoke" \
  -H "Content-Type: application/json" \
  -H "X-Api-Access-Key: ak_live_d83e201048b94103" \
  -H "X-Api-Timestamp: 1789461000000" \
  -H "X-Api-Nonce: 00112233445566778899aabbccddeeff" \
  -H "X-Api-Signature: SIGNATURE_BASE64" \
  -H "X-Api-Enterprise-Id: 1002" \
  -d '{
    "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "reason": "甲乙双方协商一致提前终止合作协议"
  }'

响应数据结构 (Response Body)

字段名 类型 详细说明
document_id string 被撤销文档的唯一 UUID。
status string 文档最终状态,固定为 voided(已作废)。
already_revoked boolean false 表示本次请求成功完成了撤销;true 表示该文档此前已被撤销,未发生状态变更。

响应示例 (Response Example)

200 OK (成功)
{
  "code": 0,
  "message": "success",
  "data": {
    "document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "voided",
    "already_revoked": false
  },
  "request_id": "req_68dfb7829a10ef4"
}

相关错误码 (Error Codes)

全部公共状态码与安全拦截说明请参阅:全局错误码字典 (Error Codes)

HTTP 状态 错误码 (code) 错误标识 (Constant) 产生原因与排查指引
404 40401 NOT_FOUND 文档 ID 不存在,或当前凭证无权操作此文档。
409 40901 RESOURCE_CONFLICT 文档已全部签署完成(状态为 completed),不可再行撤销。