在使用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 DocuSigneSignApiException 如果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'; // 替换为你要查询的信封IDtry { $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 (DocuSigneSignApiException $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调用可能因网络问题、认证失败、权限不足或无效参数而失败。务必实现健壮的错误处理机制，捕获并处理DocuSigneSignApiException。事件描述解析的鲁棒性： 尽管eventDescription通常包含取消原因，但在某些情况下，原因可能位于data字段中，或者描述的格式可能不完全一致。在生产环境中，可能需要更复杂的字符串匹配（例如正则表达式）来精确提取原因，或者检查data字段以获取额外信息。性能考量： 对于包含大量事件的信封，审计日志可能会非常大。按需获取数据，并考虑对常用信封的审计信息进行缓存，以减少API调用次数和提高应用程序性能。权限要求： 确保用于API调用的集成用户（或OAuth令牌对应的用户）拥有足够的权限来访问信封的审计日志。通常，这需要envelope_read和audit_read等相关权限。
总结
通过DocuSign API获取信封取消原因需要跳出简单的getEnvelope调用，转而利用更强大的审计日志功能。通过获取并解析信封的审计事件列表，开发者可以准确地识别信封被作废或取消的事件，并从中提取出详细的原因。这种方法不仅提供了对信封生命周期更深层次的洞察，也使得应用程序能够提供更丰富、更准确的用户反馈，从而提升整体用户体验和业务处理效率。
以上就是DocuSign API：获取信封取消原因的专业指南的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1339267.html
微信扫一扫 
支付宝扫一扫 
