本文详细阐述如何通过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方法实现。
ProfilePicture.AI 在线创建自定义头像的工具
67 查看详情 
以下是获取信封审计事件的PHP代码示例：
<?phpnamespace App\Services;use DocuSign\eSign\Api\EnvelopesApi;use DocuSign\eSign\Client\ApiClient;use DocuSign\eSign\Configuration;use Exception;class DocusignEnvelopeService{ private $token; private $envelope_id; private $account_id; public function __construct(string $token, string $envelope_id, string $account_id) { $this->token = $token; $this->envelope_id = $envelope_id; $this->account_id = $account_id; } 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; } } 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-youjiankuohaophpcngetDescription()（或类似方法）中包含“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信封生命周期管理和问题诊断的能力。
以上就是DocuSign API：获取信封取消或拒绝原因的详细教程的详细内容，更多请关注php中文网其它相关文章！
