DocuSign API获取信封取消原因教程

本文详细阐述如何通过DocuSign API获取信封被取消或签署人拒绝的具体原因。不同于简单的getEnvelope调用，获取此类详细信息需要查询信封的审计追踪（Audit Trail）。教程将指导您如何调用相关API获取审计事件列表，并从中解析出信封取消或拒绝的事件及其附带的原因。

理解DocuSign信封状态与详细原因

在使用DocuSign API管理电子签名流程时，开发者经常需要获取信封的当前状态。虽然EnvelopesApi::getEnvelope方法可以提供信封的总体状态（例如“已发送”、“已完成”、“已作废”等），但它通常不包含导致信封取消或签署人拒绝的具体文字原因。例如，当一个信封被作废（Voided）或被签署人拒绝（Rejected）时，用户通常会输入一个理由，而这个理由并不会直接通过getEnvelope调用返回。

要获取这些详细的、用户输入的取消或拒绝原因，我们需要深入到DocuSign的审计追踪机制。

解决方案：利用信封审计追踪（Audit Trail）

DocuSign为每个信封维护一个详细的审计追踪日志，记录了信封生命周期中的所有关键事件。这些事件包括信封的创建、发送、签署、作废、拒绝等，并且许多事件都附带了详细的上下文信息，包括用户输入的理由。

获取信封的取消或拒绝原因的关键在于：

1. 调用DocuSign API获取特定信封的审计事件列表。
2. 遍历这些事件，查找与取消或拒绝相关的事件类型。
3. 从找到的事件对象中提取出详细的原因描述。

获取审计事件列表

DocuSign API提供了专门的端点来获取信封的审计事件。在PHP SDK中，这通常通过EnvelopesApi::getAuditEvents方法实现。

以下是获取信封审计事件的PHP代码示例：

token = $token;
        $this->envelope_id = $envelope_id;
        $this->account_id = $account_id;
    }

    /**
     * 获取DocuSign信封的审计事件列表
     *
     * @return array|null 审计事件列表或null（如果发生错误）
     */
    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;
        }
    }

    /**
     * 从审计事件中解析出信封取消或拒绝的原因
     *
     * @return string|null 取消或拒绝的原因，如果没有找到则返回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->getDescription()（或类似方法）中包含“Voided”（作废）或“Rejected”（拒绝）等关键词的事件。
• 提取原因： 一旦找到匹配的事件，原因通常会存储在该事件对象的特定字段中，例如getReason()或getVoidReason()。有时，原因也可能嵌入在description字段中，需要通过正则表达式等方式进行解析。请务必查阅DocuSign官方API文档或SDK返回的对象结构，以确定确切的字段名。

注意事项

1. API权限： 确保您的DocuSign集成应用具有访问审计事件的必要权限。通常，这需要signature和extended范围。
2. 事件多样性： DocuSign的审计事件类型非常丰富。除了“Voided”和“Rejected”，还可能有其他导致信封终止的事件。根据您的具体需求，可能需要识别和处理更多事件类型。例如，信封也可能因系统错误而终止，这些事件的描述和原因字段可能有所不同。
3. SDK版本： DocuSign SDK的API调用和返回对象结构可能会随版本更新而变化。请参考您所使用的SDK版本的官方文档，以确保代码的兼容性和准确性。
4. 错误处理： 在实际生产环境中，务必对API调用进行健壮的错误处理，包括网络问题、认证失败、API限流等。使用try-catch块捕获DocuSign\eSign\Client\ApiException是最佳实践。
5. 性能考虑： 对于具有大量事件的信封，获取和解析审计追踪可能会消耗一定的资源。虽然getAuditEvents通常返回所有事件，但如果API支持分页，可以考虑利用它来优化性能。

总结

要获取DocuSign信封被取消或拒绝的详细原因，不能仅仅依赖于getEnvelope方法。核心策略是利用EnvelopesApi::getAuditEvents方法获取信封的完整审计追踪，然后通过遍历和解析这些事件，定位到相关的取消或拒绝事件，并从中提取出用户提供的具体原因。理解并正确实现这一机制，将大大增强您对DocuSign信封生命周期管理和问题诊断的能力。