DocuSign API的getEnvelope方法无法直接获取信封的取消原因。要获取此信息，开发者需要通过API检索信封的审计事件（Audit Events）列表。然后，遍历这些事件，查找与信封作废或取消相关的特定事件，从中提取详细的取消理由。
在DocuSign的API开发实践中，许多开发者在尝试获取信封（Envelope）的详细状态时，会首先想到使用EnvelopesApi::getEnvelope方法。然而，该方法主要返回信封的元数据和当前状态，并不直接包含信封被作废（Void）或拒绝（Declined）时的具体原因。要获取这一关键信息，我们需要深入到信封的审计追踪（Audit Trail）中。
1. 理解DocuSign审计事件
DocuSign信封的审计追踪记录了信封生命周期中的每一个重要事件，包括创建、发送、签名、查看、作废、拒绝等。每个事件都包含时间戳、执行者以及相关的详细信息。信封的取消或作废原因，就作为特定审计事件的一部分被记录下来。通过分析这些事件，我们可以精确地追踪信封状态变化的来龙去脉。
2. 通过API获取信封审计事件
要获取信封的审计事件，我们需要使用EnvelopesApi中的getAuditEvents方法。这个方法将返回一个包含信封所有历史事件的列表。
以下是一个使用PHP DocuSign eSign SDK获取审计事件并解析取消原因的示例代码：
accessToken = $accessToken;
$this->accountId = $accountId;
$this->envelopeId = $envelopeId;
$config = new Configuration();
$config->setHost($basePath);
$config->addDefaultHeader('Authorization', 'Bearer ' . $this->accessToken);
$this->apiClient = new ApiClient($config);
}
/**
* 获取DocuSign信封的审计事件列表。
*
* @return array|null 审计事件列表（EnvelopeAuditEvent对象数组）或null（如果发生错误）
*/
public function getEnvelopeAuditEvents(): ?array
{
try {
$envelopeApi = new EnvelopesApi($this->apiClient);
/** @var EnvelopeAuditEvents $results */
$results = $envelopeApi->getAuditEvents($this->accountId, $this->envelopeId);
return $results->getEvents(); // 获取事件数组
} catch (\DocuSign\eSign\Client\ApiException $e) {
error_log("DocuSign API Error fetching audit events: " . $e->getMessage());
// 可以在此处添加更详细的错误处理和日志记录
return null;
} catch (Exception $e) {
error_log("General Error fetching audit events: " . $e->getMessage());
return null;
}
}
/**
* 从审计事件中解析信封的取消或作废原因。
*
* @return string|null 取消原因字符串或null（如果未找到）
*/
public function parseCancellationReason(): ?string
{
$events = $this->getEnvelopeAuditEvents();
if (empty($events)) {
return null;
}
foreach ($events as $event) {
// 审计事件对象（EnvelopeAuditEvent）通常包含以下方法来获取信息
// getEventDescription()：事件描述，如 "Envelope Voided"
// getEventFields()：一个包含额外字段（如原因）的数组
$eventDescription = $event->getEventDescription();
// 检查事件描述是否包含“Voided”或“Cancelled”
if (strpos($eventDescription, 'Voided') !== false || strpos($eventDescription, 'Cancelled') !== false) {
$eventFields = $event->getEventFields();
if (!empty($eventFields)) {
foreach ($eventFields as $field) {
// 查找名为 'Reason' 或 'VoidReason' 的字段
if (isset($field['name']) && ($field['name'] === 'Reason' || $field['name'] === 'VoidReason') && isset($field['value'])) {
return $field['value'];
}
}
}
// 如果在eventFields中未找到，尝试从eventDescription中解析
// 这种方式是备用方案，可能需要更复杂的字符串匹配
// 例如，"Envelope Voided by [User Name] with reason: [Reason Text]"
if (preg_match('/reason:\s*(.+)/i', $eventDescription, $matches)) {
return $matches[1];
}
}
}
return null; // 未找到取消原因
}
}
// 示例用法：
// $accessToken = 'YOUR_DOCUSIGN_ACCESS_TOKEN'; // 从OAuth流程获取
// $accountId = 'YOUR_DOCUSIGN_ACCOUNT_ID'; // DocuSign账户ID
// $envelopeId = 'YOUR_DOCUSIGN_ENVELOPE_ID'; // 目标信封ID
// $basePath = 'https://demo.docusign.net/restapi'; // 沙箱环境URL，生产环境为 'https://www.docusign.net/restapi'
// $service = new DocuSignEnvelopeService($accessToken, $accountId, $envelopeId, $basePath);
// $cancellationReason = $service->parseCancellationReason();
// if ($cancellationReason !== null) {
// echo "信封取消原因: " . $cancellationReason . "\n";
// } else {
// echo "未找到信封取消原因或信封未被取消。\n";
// }
?>代码说明：
- DocuSignEnvelopeService 类封装了与DocuSign API交互的逻辑，包括API客户端的配置和初始化。
- getEnvelopeAuditEvents() 方法负责调用DocuSign API的getAuditEvents接口，获取信封的所有审计事件。该方法返回一个EnvelopeAuditEvents对象，其events属性包含一个EnvelopeAuditEvent对象数组。
- parseCancellationReason() 方法遍历获取到的EnvelopeAuditEvent对象列表。它通过检查每个事件的eventDescription来识别作废或取消事件（例如，包含“Voided”或“Cancelled”字样）。
- 关键解析逻辑：作废原因通常包含在事件的eventFields属性中，以name为Reason或VoidReason的字段存在。在某些情况下，原因也可能直接嵌入在eventDescription字符串中，此时需要通过正则表达式进行提取。请务必参考DocuSign官方API文档或实际API响应来确定确切的字段名和结构，以确保解析的准确性。
3. 注意事项与最佳实践
- API权限：确保您的DocuSign集成用户（通常是OAuth令牌对应的用户）拥有足够的权限来访问信封的审计事件。通常需要envelope_read或更高级别的权限。
- 错误处理：在生产环境中，务必对API调用进行健壮的错误处理。捕获DocuSign\eSign\Client\ApiException可以处理API返回的特定错误，而通用的Exception则可以捕获其他运行时错误。建议将错误信息记录到日志系统。
- 事件结构与版本：DocuSign API的事件结构可能会随着API版本的更新而有细微调整。在升级SDK或API版本后，请验证您的解析逻辑是否仍然有效，并参考最新的API文档。
- 性能考量：对于具有大量操作历史的信封，获取和解析审计事件可能需要一定时间。如果需要频繁查询，可以考虑在必要时缓存结果或优化查询逻辑。
- 作废与拒绝：本教程主要关注信封的“作废”（Void）原因。如果需要获取签名者“拒绝”（Declined）信封的原因，处理逻辑类似，但需要在审计事件中查找“Declined”相关的事件，并从其eventFields中提取拒绝理由。
总结
获取DocuSign信封的取消或作废原因不能通过简单的getEnvelope调用实现。正确的做法是利用DocuSign API提供的getAuditEvents方法，获取信封的完整审计事件列表。然后，通过遍历并解析这些事件，定位到作废事件，并从中提取出详细的取消理由。这种方法确保了对信封生命周期中关键状态变化的全面追踪和理解，对于构建健壮的DocuSign集成应用至关重要。
