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 (DocuSigneSignClientApiException $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调用进行健壮的错误处理。捕获DocuSigneSignClientApiException可以处理API返回的特定错误，而通用的Exception则可以捕获其他运行时错误。建议将错误信息记录到日志系统。事件结构与版本：DocuSign API的事件结构可能会随着API版本的更新而有细微调整。在升级SDK或API版本后，请验证您的解析逻辑是否仍然有效，并参考最新的API文档。性能考量：对于具有大量操作历史的信封，获取和解析审计事件可能需要一定时间。如果需要频繁查询，可以考虑在必要时缓存结果或优化查询逻辑。作废与拒绝：本教程主要关注信封的“作废”（Void）原因。如果需要获取签名者“拒绝”（Declined）信封的原因，处理逻辑类似，但需要在审计事件中查找“Declined”相关的事件，并从其eventFields中提取拒绝理由。
总结
获取DocuSign信封的取消或作废原因不能通过简单的getEnvelope调用实现。正确的做法是利用DocuSign API提供的getAuditEvents方法，获取信封的完整审计事件列表。然后，通过遍历并解析这些事件，定位到作废事件，并从中提取出详细的取消理由。这种方法确保了对信封生命周期中关键状态变化的全面追踪和理解，对于构建健壮的DocuSign集成应用至关重要。
以上就是获取DocuSign信封取消原因的API教程的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1340389.html
微信扫一扫 
支付宝扫一扫 
