本文详细阐述如何通过docusign api获取信封被取消或签署人拒绝的具体原因。不同于简单的getenvelope调用，获取此类详细信息需要查询信封的审计追踪（audit trail）。教程将指导您如何调用相关api获取审计事件列表，并从中解析出信封取消或拒绝的事件及其附带的原因。
理解DocuSign信封状态与详细原因
在使用DocuSign API管理电子签名流程时，开发者经常需要获取信封的当前状态。虽然EnvelopesApi::getEnvelope方法可以提供信封的总体状态（例如“已发送”、“已完成”、“已作废”等），但它通常不包含导致信封取消或签署人拒绝的具体文字原因。例如，当一个信封被作废（Voided）或被签署人拒绝（Rejected）时，用户通常会输入一个理由，而这个理由并不会直接通过getEnvelope调用返回。
要获取这些详细的、用户输入的取消或拒绝原因，我们需要深入到DocuSign的审计追踪机制。
解决方案：利用信封审计追踪（Audit Trail）
DocuSign为每个信封维护一个详细的审计追踪日志，记录了信封生命周期中的所有关键事件。这些事件包括信封的创建、发送、签署、作废、拒绝等，并且许多事件都附带了详细的上下文信息，包括用户输入的理由。
获取信封的取消或拒绝原因的关键在于：
- 调用DocuSign API获取特定信封的审计事件列表。
- 遍历这些事件，查找与取消或拒绝相关的事件类型。
- 从找到的事件对象中提取出详细的原因描述。
获取审计事件列表
DocuSign API提供了专门的端点来获取信封的审计事件。在PHP SDK中，这通常通过EnvelopesApi::getAuditEvents方法实现。
以下是获取信封审计事件的PHP代码示例：
token = $token;
$this->envelope_id = $envelope_id;
$this->account_id = $account_id;
}
/**
* 获取DocuSign信封的审计事件列表
*
* @return array|null 审计事件列表或null（如果发生错误）
*/
public function getEnvelopeAuditEvents(): ?array
{
try {
$config = new Configuration();
$config->setHost(env('DOCUSIGN_BASE_URL'));
$config->addDefaultHeader('Authorization', 'Bearer ' . $this->token);
$api_client = new ApiClient($config);
$envelope_api = new EnvelopesApi($api_client);
// 调用getAuditEvents方法获取审计事件
// 该方法返回一个EnvelopeAuditEventResponse对象，其中包含一个auditEvents数组。
$auditEventsResponse = $envelope_api->getAuditEvents($this->account_id, $this->envelope_id);
if ($auditEventsResponse && $auditEventsResponse->getAuditEvents()) {
return $auditEventsResponse->getAuditEvents();
}
return null;
} catch (Exception $e) {
// 捕获并处理API调用过程中可能发生的异常
error_log("Error fetching DocuSign audit events: " . $e->getMessage());
return null;
}
}
/**
* 从审计事件中解析出信封取消或拒绝的原因
*
* @return string|null 取消或拒绝的原因，如果没有找到则返回null
*/
public function getCancellationOrRejectionReason(): ?string
{
$auditEvents = $this->getEnvelopeAuditEvents();
if (empty($auditEvents)) {
return null;
}
foreach ($auditEvents as $event) {
// 审计事件对象通常包含一个'description'字段来描述事件类型
// 常见的取消/拒绝事件描述可能包括 "Envelope Voided", "Recipient Rejected" 等
$eventDescription = $event->getDescription(); // 假设DocuSign SDK的EnvelopeAuditEvent对象有getDescription()方法
if (strpos($eventDescription, 'Voided') !== false || strpos($eventDescription, 'Rejected') !== false) {
// 如果事件描述包含“Voided”或“Rejected”，则尝试提取原因
// 原因通常在事件对象的某个字段中，例如'reason'或'voidReason'
// 具体的字段名需要根据实际的API响应结构来确定
// 这里假设存在getReason()或getVoidReason()方法
if (method_exists($event, 'getReason') && $event->getReason()) {
return $event->getReason();
}
if (method_exists($event, 'getVoidReason') && $event->getVoidReason()) {
return $event->getVoidReason();
}
// 有些情况下，原因可能直接包含在description中，或者需要更复杂的解析
// 例如： "Envelope Voided by Sender. Reason: [Your Reason Here]"
if (preg_match('/Reason:\s*(.*)/i', $eventDescription, $matches)) {
return trim($matches[1]);
}
}
}
return null; // 未找到取消或拒绝原因
}
}
// 示例用法：
// $yourAccessToken = 'YOUR_DOCUSIGN_ACCESS_TOKEN';
// $yourEnvelopeId = 'YOUR_DOCUSIGN_ENVELOPE_ID';
// $yourAccountId = env('DOCUSIGN_ACCOUNT_ID'); // 从环境变量获取账户ID
// $docusignService = new DocusignEnvelopeService($yourAccessToken, $yourEnvelopeId, $yourAccountId);
// $reason = $docusignService->getCancellationOrRejectionReason();
// if ($reason) {
// echo "信封取消/拒绝原因：" . $reason . PHP_EOL;
// } else {
// echo "未找到信封取消/拒绝原因或信封未被取消/拒绝。" . PHP_EOL;
// }代码说明：
- DocusignEnvelopeService 类封装了与DocuSign API交互的逻辑。
- getEnvelopeAuditEvents 方法负责初始化DocuSign API客户端并调用EnvelopesApi::getAuditEvents来获取审计事件列表。
- getCancellationOrRejectionReason 方法则遍历获取到的审计事件。
- 关键点： 识别事件类型。你需要查找event->getDescription()（或类似方法）中包含“Voided”（作废）或“Rejected”（拒绝）等关键词的事件。
- 提取原因： 一旦找到匹配的事件，原因通常会存储在该事件对象的特定字段中，例如getReason()或getVoidReason()。有时，原因也可能嵌入在description字段中，需要通过正则表达式等方式进行解析。请务必查阅DocuSign官方API文档或SDK返回的对象结构，以确定确切的字段名。
注意事项
- API权限： 确保您的DocuSign集成应用具有访问审计事件的必要权限。通常，这需要signature和extended范围。
- 事件多样性： DocuSign的审计事件类型非常丰富。除了“Voided”和“Rejected”，还可能有其他导致信封终止的事件。根据您的具体需求，可能需要识别和处理更多事件类型。例如，信封也可能因系统错误而终止，这些事件的描述和原因字段可能有所不同。
- SDK版本： DocuSign SDK的API调用和返回对象结构可能会随版本更新而变化。请参考您所使用的SDK版本的官方文档，以确保代码的兼容性和准确性。
- 错误处理： 在实际生产环境中，务必对API调用进行健壮的错误处理，包括网络问题、认证失败、API限流等。使用try-catch块捕获DocuSign\eSign\Client\ApiException是最佳实践。
- 性能考虑： 对于具有大量事件的信封，获取和解析审计追踪可能会消耗一定的资源。虽然getAuditEvents通常返回所有事件，但如果API支持分页，可以考虑利用它来优化性能。
总结
要获取DocuSign信封被取消或拒绝的详细原因，不能仅仅依赖于getEnvelope方法。核心策略是利用EnvelopesApi::getAuditEvents方法获取信封的完整审计追踪，然后通过遍历和解析这些事件，定位到相关的取消或拒绝事件，并从中提取出用户提供的具体原因。理解并正确实现这一机制，将大大增强您对DocuSign信封生命周期管理和问题诊断的能力。
