本教程详细介绍了如何通过docusign api获取信封的取消或拒绝原因。不同于直接使用`getenvelope`方法，获取此类信息需要查询信封的审计事件列表。文章将指导您如何利用docusign sdk获取审计事件，并从事件描述中解析出具体的取消或拒绝原因，提供示例代码和注意事项，帮助开发者准确追踪信封状态变更的详细情况。
在DocuSign的开发实践中，有时我们需要了解一个信封为何被取消（作废）或被收件人拒绝。标准的getEnvelope API调用通常会返回信封的当前状态和基本信息，但并不会直接提供详细的取消或拒绝原因。要获取这些具体原因，我们需要深入到信封的审计事件（Audit Trail）中进行查找。
1. 理解DocuSign审计事件
DocuSign的每个信封都维护着一个详细的审计日志，记录了信封生命周期中的所有重要事件，例如创建、发送、查看、签署、拒绝、作废等。每个事件都包含事件名称、描述、时间戳以及执行该操作的用户信息。信封的取消或拒绝原因通常作为特定事件（如“信封作废”或“收件人拒绝”）的描述一部分被记录下来。
2. 获取信封审计事件列表
要获取信封的审计事件，我们需要使用DocuSign eSign API提供的专门方法，而不是普通的getEnvelope。在PHP SDK中，这通常通过EnvelopesApi类的listAuditEvents方法来实现。
以下是一个PHP示例代码，展示如何配置DocuSign API客户端并调用listAuditEvents方法来获取指定信封的所有审计事件：
token = $token;
$this->envelopeId = $envelopeId;
$config = new Configuration();
// 设置DocuSign API基础URL，通常从环境变量获取
$config->setHost(env('DOCUSIGN_BASE_URL'));
// 添加授权头
$config->addDefaultHeader('Authorization', 'Bearer ' . $this->token);
$this->apiClient = new ApiClient($config);
$this->envelopesApi = new EnvelopesApi($this->apiClient);
}
/**
* 获取DocuSign信封的取消或拒绝原因。
*
* @return string|null 返回取消或拒绝原因的详细描述，如果未找到则返回null。
* @throws \Exception 如果API调用或处理过程中发生错误。
*/
public function getEnvelopeCancellationReason(): ?string
{
try {
// 获取信封的审计事件列表
// DocuSign SDK的listAuditEvents方法返回一个AuditEvents对象，
// 其中包含一个AuditEvent对象数组。
$auditEventsResponse = $this->envelopesApi->listAuditEvents(
env('DOCUSIGN_ACCOUNT_ID'), // DocuSign账户ID，通常从环境变量获取
$this->envelopeId
);
// 检查响应中是否包含审计事件
if (empty($auditEventsResponse) || !isset($auditEventsResponse->getAuditEvents())) {
return null;
}
// 遍历所有审计事件，查找信封作废或收件人拒绝的事件
foreach ($auditEventsResponse->getAuditEvents() as $event) {
$eventName = $event->getEventName();
$eventDescription = $event->getEventDescription();
// 根据DocuSign的事件名称识别关键事件
// "EnvelopeVoided" 表示信封被作废或取消
// "RecipientDeclined" 表示收件人拒绝签署
if ($eventName === 'EnvelopeVoided' || $eventName === 'RecipientDeclined') {
// 这些事件的详细原因通常包含在event_description字段中。
// 您可能需要进一步解析此字符串以提取最核心的原因。
// 例如，"信封被 [用户名] 作废，原因：[具体原因]"
// 或者 "收件人 [用户名] 拒绝签署，原因：[具体原因]"
return $eventDescription;
}
}
return null; // 未找到信封的取消或拒绝事件
} catch (ApiException $e) {
// 捕获DocuSign API调用过程中可能发生的异常
throw new \Exception("DocuSign API错误: " . $e->getMessage(), $e->getCode(), $e);
} catch (\Exception $e) {
// 捕获其他通用异常
throw new \Exception("处理DocuSign信封审计事件时发生错误: " . $e->getMessage(), $e->getCode(), $e);
}
}
}3. 解析审计事件以提取原因
在上述代码中，我们遍历了auditEventsResponse->getAuditEvents()返回的AuditEvent对象数组。对于每个事件，我们检查其eventName和eventDescription：
- eventName: 这是一个标准化的事件标识符。例如，EnvelopeVoided表示信封已被作废或取消，RecipientDeclined表示某个收件人拒绝了签署。
- eventDescription: 这是事件的详细文本描述，通常包含了操作的具体上下文和原因。对于EnvelopeVoided或RecipientDeclined事件，其描述中会包含用户输入的取消或拒绝理由。
示例代码直接返回了eventDescription。在实际应用中，如果需要更精细地提取原因，您可能需要对eventDescription字符串进行进一步的解析，例如使用正则表达式或字符串查找函数来提取"原因："后面的文本。
4. 注意事项
- DocuSign SDK版本: 确保您使用的DocuSign SDK版本支持listAuditEvents方法。不同版本的SDK可能在方法命名或返回对象结构上略有差异。
- 权限: 调用listAuditEvents需要相应的API权限。确保您的集成密钥（Integration Key）拥有足够的权限来访问信封的审计信息。
- 错误处理: 务必实现健壮的错误处理机制，捕获ApiException以及其他可能的运行时异常，以便在API调用失败时能够妥善处理。
- 事件类型多样性: DocuSign的事件类型非常丰富。除了EnvelopeVoided和RecipientDeclined，可能还有其他与信封状态变更相关的事件，具体取决于您的业务场景。
- 性能考量: 对于包含大量事件的信封，listAuditEvents可能会返回较多的数据。在处理大量信封时，请考虑API的速率限制和响应时间。
总结
获取DocuSign信封的取消或拒绝原因并非通过简单的getEnvelope调用即可实现。开发者需要利用DocuSign eSign API的listAuditEvents方法来获取信封的审计事件列表，然后遍历这些事件，查找EnvelopeVoided或RecipientDeclined等关键事件，并从其eventDescription中提取出详细的原因。遵循本教程的指导和示例代码，您将能够有效地追踪和理解DocuSign信封的生命周期变更。
