在使用docusign api时，直接通过`getenvelope`方法无法获取信封被取消的具体原因。本文将详细指导开发者如何通过访问信封的审计日志（audit trail），解析其中包含的事件列表，从而准确地查找并提取信封被作废或取消的详细原因，确保应用程序能够全面追踪信封状态。
1. 理解信封取消状态与API限制
当DocuSign信封被签署人拒绝、作废（void）或取消（cancel）时，其状态会发生变化。开发者通常会使用EnvelopesApi::getEnvelope方法来获取信封的当前状态。然而，此方法返回的信息通常仅包含信封的概览状态（如voided或declined），但并不会直接提供导致取消或作废的具体理由。例如，如果一个信封被作废，getEnvelope可能只会显示其状态为voided，而不会告知“为什么”被作废。
为了满足业务需求，例如向用户提供详细的反馈或进行内部审计，获取信封取消的具体原因至关重要。这就需要我们深入DocuSign API提供的更细粒度的数据——审计日志。
2. 核心方案：利用审计日志（Audit Trail）
DocuSign为每个信封维护一个详细的审计日志（Audit Trail），它记录了信封生命周期中的所有关键事件。这些事件包括信封的创建、发送、查看、签署、拒绝以及作废等操作。当信封被取消或作废时，相关的事件及其原因都会被记录在这个审计日志中。
因此，获取信封取消原因的核心方案是：
- 通过DocuSign API获取目标信封的审计事件列表。
- 遍历审计事件列表，识别出表示信封被作废或取消的事件。
- 从该事件的详细信息中提取出取消的具体原因。
3. 获取信封审计日志
DocuSign API提供了专门的端点来获取信封的审计事件。在PHP SDK中，这通常通过EnvelopesApi类的一个方法实现，例如getAuditEvents。
以下是一个使用PHP DocuSign eSign SDK获取信封审计事件的示例代码：
accountId = $accountId;
$config = new Configuration();
$config->setHost($baseUrl);
$config->addDefaultHeader('Authorization', 'Bearer ' . $accessToken);
$this->apiClient = new ApiClient($config);
}
/**
* 获取指定信封的审计事件列表
* @param string $envelopeId 信封ID
* @return EnvelopeAuditEvents 包含审计事件列表的对象
* @throws \DocuSign\eSign\ApiException 如果API调用失败
*/
public function getEnvelopeAuditEvents(string $envelopeId): EnvelopeAuditEvents {
$envelopeApi = new EnvelopesApi($this->apiClient);
// 调用EnvelopesApi的getAuditEvents方法来获取信封的审计事件
// 对应的REST API端点是 GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/audit_events
return $envelopeApi->getAuditEvents($this->accountId, $envelopeId);
}
/**
* 解析审计事件，查找信封取消原因
* @param EnvelopeAuditEvents $auditEvents 审计事件对象
* @return string|null 取消原因，如果找到则返回字符串，否则返回null
*/
public function parseCancellationReason(EnvelopeAuditEvents $auditEvents): ?string {
// 检查审计事件列表是否存在
if (empty($auditEvents->getAuditEvents())) {
return null;
}
foreach ($auditEvents->getAuditEvents() as $event) {
// DocuSign的事件对象通常包含 'eventDescription' 字段来描述事件
// 'voided' 或 'cancelled' 是常见的取消/作废关键词
$description = $event->getEventDescription();
if ($description && (str_contains(strtolower($description), 'voided') || str_contains(strtolower($description), 'cancelled'))) {
// 找到取消或作废事件
// 审计事件的描述通常会直接包含取消原因，例如 "Envelope was voided by [User Name] with reason: [Cancellation Reason]"
// 或者 "Envelope voided with reason: [Cancellation Reason]"
return $description; // 返回包含原因的完整描述
}
}
return null;
}
}注意事项：
- 请确保您的DocuSign SDK已正确安装并配置。
- $accessToken 应是一个有效的OAuth2访问令牌。
- $accountId 是您的DocuSign账户ID。
- $baseUrl 应指向正确的DocuSign API环境（例如，沙盒环境为https://demo.docusign.net/restapi，生产环境为https://www.docusign.net/restapi）。
- DocuSign SDK和API可能会有版本更新，请查阅最新的官方文档以确认方法名和模型结构。
4. 解析审计事件，查找取消原因
获取到EnvelopeAuditEvents对象后，它会包含一个auditEvents数组，其中每个元素都是一个AuditEvent对象。每个AuditEvent对象通常包含以下关键字段：
- eventDateTime: 事件发生的时间。
- eventDescription: 事件的详细描述。
- data: 包含更多事件相关数据的对象或数组。
我们需要遍历这个auditEvents数组，查找那些描述中包含“voided”（作废）或“cancelled”（取消）等关键词的事件。一旦找到这样的事件，其eventDescription字段通常就会包含具体的取消原因。
在上述DocusignEnvelopeAuditor类中，parseCancellationReason方法演示了如何进行这一解析。
使用示例：
// 假设您已在环境变量中配置了这些信息
$accessToken = getenv('DOCUSIGN_ACCESS_TOKEN');
$accountId = getenv('DOCUSIGN_ACCOUNT_ID');
$baseUrl = getenv('DOCUSIGN_BASE_URL');
$envelopeId = 'YOUR_ENVELOPE_ID'; // 替换为你要查询的信封ID
try {
$auditor = new DocusignEnvelopeAuditor($accessToken, $accountId, $baseUrl);
$auditEvents = $auditor->getEnvelopeAuditEvents($envelopeId);
$cancellationReason = $auditor->parseCancellationReason($auditEvents);
if ($cancellationReason) {
echo "信封ID: {$envelopeId} 的取消原因: " . $cancellationReason . "\n";
} else {
echo "信封ID: {$envelopeId} 未找到明确的取消原因，或信封未被取消。\n";
}
} catch (\DocuSign\eSign\ApiException $e) {
echo "DocuSign API调用错误: " . $e->getMessage() . "\n";
// 根据需要进行更详细的错误处理，例如记录日志或通知管理员
if ($e->getResponseBody()) {
echo "错误响应体: " . $e->getResponseBody() . "\n";
}
} catch (Exception $e) {
echo "发生未知错误: " . $e->getMessage() . "\n";
}5. 注意事项与最佳实践
- API版本兼容性： DocuSign API及其SDK会不断更新。本文提供的代码基于常见的SDK结构，但具体方法名和模型字段可能因您使用的SDK版本而异。务必查阅DocuSign官方开发者文档以获取最新和最准确的信息。
- 错误处理： API调用可能因网络问题、认证失败、权限不足或无效参数而失败。务必实现健壮的错误处理机制，捕获并处理\DocuSign\eSign\ApiException。
- 事件描述解析的鲁棒性： 尽管eventDescription通常包含取消原因，但在某些情况下，原因可能位于data字段中，或者描述的格式可能不完全一致。在生产环境中，可能需要更复杂的字符串匹配（例如正则表达式）来精确提取原因，或者检查data字段以获取额外信息。
- 性能考量： 对于包含大量事件的信封，审计日志可能会非常大。按需获取数据，并考虑对常用信封的审计信息进行缓存，以减少API调用次数和提高应用程序性能。
- 权限要求： 确保用于API调用的集成用户（或OAuth令牌对应的用户）拥有足够的权限来访问信封的审计日志。通常，这需要envelope_read和audit_read等相关权限。
总结
通过DocuSign API获取信封取消原因需要跳出简单的getEnvelope调用，转而利用更强大的审计日志功能。通过获取并解析信封的审计事件列表，开发者可以准确地识别信封被作废或取消的事件，并从中提取出详细的原因。这种方法不仅提供了对信封生命周期更深层次的洞察，也使得应用程序能够提供更丰富、更准确的用户反馈，从而提升整体用户体验和业务处理效率。
