撤销效果与幂等保证
文档撤销后不可逆转恢复。一旦执行成功,所有签署人打开签署链接时均会提示“该文档已被发起人撤销”。本接口具备天然状态幂等特性,重复撤销同一已撤销文档不会报错,响应中的
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": "甲乙双方协商一致提前终止合作协议"
}'
<?php
use DsignSdk\DsignClient;
$client = new DsignClient([
'base_url' => 'https://api.example.com',
'access_key' => 'ak_live_d83e201048b94103',
'secret_key' => 'sk_live_948f2038102941029',
'enterprise_id' => '1002',
]);
$result = $client->documents->revoke([
'document_id' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',
'reason' => '甲乙双方协商一致提前终止合作协议',
]);
echo "文档撤销完成,当前状态: " . $result['status'];
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.UUID;
public class RevokeDocumentDemo {
public static void main(String[] args) throws Exception {
String accessKey = "ak_live_d83e201048b94103";
String secretKey = "sk_live_948f2038102941029";
String enterpriseId = "1002";
long timestampMs = System.currentTimeMillis();
String nonce = UUID.randomUUID().toString().replace("-", "");
String jsonBody = "{\n" +
" \"document_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n" +
" \"reason\": \"甲乙双方协商一致提前终止合作协议\"\n" +
"}";
String signature = DsignSigner.buildSignature(
secretKey, "POST", "/open/documents/revoke", "", jsonBody,
timestampMs, nonce, enterpriseId, ""
);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.example.com/open/documents/revoke"))
.header("Content-Type", "application/json; charset=utf-8")
.header("X-Api-Access-Key", accessKey)
.header("X-Api-Timestamp", String.valueOf(timestampMs))
.header("X-Api-Nonce", nonce)
.header("X-Api-Signature", signature)
.header("X-Api-Enterprise-Id", enterpriseId)
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP 状态码: " + response.statusCode());
System.out.println("撤销响应: " + response.body());
}
}
import requests, json
resp = requests.post("https://api.example.com/open/documents/revoke",
headers=headers,
data=json.dumps({
"document_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"reason": "信息录入错误需重新发起"
})
)
print(resp.json())
const axios = require('axios');
axios.post('https://api.example.com/open/documents/revoke', {
document_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
reason: '信息录入错误'
}, { headers }).then(res => console.log(res.data));
响应数据结构 (Response Body)
| 字段名 |
类型 |
详细说明 |
| document_id |
string |
被撤销文档的唯一 UUID。 |
| status |
string |
文档最终状态,固定为 voided(已作废)。 |
| already_revoked |
boolean |
false 表示本次请求成功完成了撤销;true 表示该文档此前已被撤销,未发生状态变更。
|
响应示例 (Response Example)
{
"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),不可再行撤销。 |