DocuSign的`getEnvelope` API调用通常无法直接获取信封的详细取消原因。要获取这一信息，需要通过DocuSign API访问信封的审计日志。审计日志记录了信封生命周期内的所有事件，包括取消操作及其原因。通过解析这些事件，可以准确提取出信封被拒绝或取消的具体理由。
在DocuSign的API中，标准获取信封状态的调用，如getEnvelope，通常会返回信封的基本信息和当前状态，但对于信封被取消或拒绝的具体原因，这些信息往往不会直接提供。为了获取这一关键细节，开发者需要深入到信封的审计事件（Audit Events）中进行查找。
1. 理解DocuSign审计日志
DocuSign信封的审计日志是一个时间序列的事件列表，记录了信封从创建到完成或取消的每一个重要操作。这包括发送、签名、查看、拒绝、取消等。当一个信封被取消（Voided）时，相关的取消原因也会作为事件的一部分被记录下来。
2. 获取信封审计事件
要获取信封的审计事件，您需要使用EnvelopesApi中专门用于此目的的方法，通常是getEnvelopeAuditEvents。这个方法会返回一个包含所有审计事件的列表。
以下是一个使用PHP的示例代码，演示如何配置DocuSign API客户端并调用getEnvelopeAuditEvents来获取信封的审计日志：
<?php
require_once(__DIR__ . '/vendor/autoload.php'); // 假设您已通过Composer安装DocuSign SDK
use DocuSign\eSign\ApiClient;
use DocuSign\eSign\Configuration;
use DocuSign\eSign\Api\EnvelopesApi;
class DocuSignEnvelopeService
{
private $apiClient;
private $accountId;
private $envelopeId;
private $accessToken;
public function __construct($accessToken, $accountId, $envelopeId, $baseUrl)
{
$this->accessToken = $accessToken;
$this->accountId = $accountId;
$this->envelopeId = $envelopeId;
$config = new Configuration();
$config->setHost($baseUrl);
$config->addDefaultHeader('Authorization', 'Bearer ' . $this->accessToken);
$this->apiClient = new ApiClient($config);
}
/**
* 获取信封的审计事件，并尝试解析取消原因
*
* @return string|null 返回取消原因，如果未找到则返回null
*/
public function getEnvelopeCancellationReason()
{
try {
$envelopeApi = new EnvelopesApi($this->apiClient);
// 调用API获取信封的审计事件
// 注意：具体方法名和参数可能因SDK版本而异，请参考DocuSign官方SDK文档
$auditEvents = $envelopeApi->getEnvelopeAuditEvents(
$this->accountId,
$this->envelopeId
);
$cancellationReason = null;
if ($auditEvents && isset($auditEvents->auditEvents)) {
foreach ($auditEvents->auditEvents as $event) {
// 寻找描述中包含“Envelope Voided”或“Envelope Cancelled”的事件
// 具体的描述文本可能因DocuSign系统语言或事件类型而异
if (isset($event->description) && strpos($event->description, 'Envelope Voided') !== false) {
// 取消原因通常包含在eventData属性中，它是一个JSON字符串
if (isset($event->eventData)) {
$eventData = json_decode($event->eventData, true);
if (isset($eventData['voidReason'])) {
$cancellationReason = $eventData['voidReason'];
break; // 找到原因后即可退出循环
}
}
}
}
}
return $cancellationReason;
} catch (\DocuSign\eSign\ApiException $e) {
// 处理API调用异常
echo "DocuSign API 错误: " . $e->getMessage() . "\n";
return null;
} catch (\Exception $e) {
// 处理其他异常
echo "发生错误: " . $e->getMessage() . "\n";
return null;
}
}
}
// 示例用法
// $accessToken = env('DOCUSIGN_ACCESS_TOKEN');
// $accountId = env('DOCUSIGN_ACCOUNT_ID');
// $envelopeId = 'YOUR_ENVELOPE_ID'; // 替换为实际的信封ID
// $baseUrl = env('DOCUSIGN_BASE_URL'); // 例如：'https://demo.docusign.net/restapi'
// $service = new DocuSignEnvelopeService($accessToken, $accountId, $envelopeId, $baseUrl);
// $reason = $service->getEnvelopeCancellationReason();
// if ($reason) {
// echo "信封取消原因: " . $reason . "\n";
// } else {
// echo "未找到信封取消原因，或信封未被取消。\n";
// }
?>3. 解析审计事件以提取取消原因
获取到auditEvents列表后，您需要遍历这个列表，查找与信封取消相关的事件。通常，取消事件会在其description属性中包含关键词，例如“Envelope Voided”（信封已作废）。
一旦找到这样的事件，取消的具体原因通常会存储在事件的eventData属性中。eventData通常是一个JSON格式的字符串，其中包含详细的事件元数据，包括voidReason（作废原因）。您需要解析这个JSON字符串来提取所需的原因。
注意事项
- API版本兼容性： DocuSign API和SDK会不断更新，上述代码示例中的方法名、属性名或返回结构可能随版本变化。请始终参考DocuSign官方开发者文档或SDK的最新示例。
- 错误处理： 在实际应用中，务必对API调用进行健壮的错误处理，包括网络问题、认证失败、权限不足或信封ID无效等情况。
- 性能考量： 对于包含大量事件的信封，getEnvelopeAuditEvents可能会返回大量数据。在处理这些数据时，应考虑性能优化。
- 事件描述多样性： 尽管“Envelope Voided”是常见的描述，但在某些特定场景或多语言环境中，描述文本可能会有所不同。如果无法找到，可能需要检查其他相关的事件描述或属性。
总结
通过利用DocuSign的审计日志功能，即使标准API调用无法直接提供，您也能够获取到信封被取消或拒绝的详细原因。关键在于调用getEnvelopeAuditEvents方法，并仔细解析返回的事件列表，特别是关注那些描述为“Envelope Voided”的事件，并从其eventData中提取voidReason。这一方法为开发者提供了深入了解信封生命周期中关键事件的强大能力。
