DocuSign API：获取信封取消原因的专业指南

<?php
require_once(__DIR__ . '/vendor/autoload.php'); // 确保DocuSign SDK已通过Composer安装

use DocuSign\eSign\ApiClient;
use DocuSign\eSign\Configuration;
use DocuSign\eSign\Api\EnvelopesApi;
use DocuSign\eSign\Model\EnvelopeAuditEvents; // 审计事件模型

class DocusignEnvelopeAuditor {
    private ApiClient $apiClient;
    private string $accountId;

    /**
     * 构造函数，初始化DocuSign API客户端
     * @param string $accessToken DocuSign OAuth2访问令牌
     * @param string $accountId DocuSign账户ID
     * @param string $baseUrl DocuSign API基础URL (例如: "https://demo.docusign.net/restapi")
     */
    public function __construct(string $accessToken, string $accountId, string $baseUrl) {
        $this->accountId = $accountId;

        $config = new Configuration();
        $config->setHost($baseUrl);
        $config->addDefaultHeader('Authorization', 'Bearer ' . $accessToken);
        $this->apiClient = new ApiClient($config);
    }

    /**
     * 获取指定信封的审计事件列表
     * @param string $envelopeId 信封ID
     * @return EnvelopeAuditEvents 包含审计事件列表的对象
     * @throws \DocuSign\eSign\ApiException 如果API调用失败
     */
    public function getEnvelopeAuditEvents(string $envelopeId): EnvelopeAuditEvents {
        $envelopeApi = new EnvelopesApi($this->apiClient);
        // 调用EnvelopesApi的getAuditEvents方法来获取信封的审计事件
        // 对应的REST API端点是 GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/audit_events
        return $envelopeApi->getAuditEvents($this->accountId, $envelopeId);
    }

    /**
     * 解析审计事件，查找信封取消原因
     * @param EnvelopeAuditEvents $auditEvents 审计事件对象
     * @return string|null 取消原因，如果找到则返回字符串，否则返回null
     */
    public function parseCancellationReason(EnvelopeAuditEvents $auditEvents): ?string {
        // 检查审计事件列表是否存在
        if (empty($auditEvents->getAuditEvents())) {
            return null;
        }

        foreach ($auditEvents->getAuditEvents() as $event) {
            // DocuSign的事件对象通常包含 'eventDescription' 字段来描述事件
            // 'voided' 或 'cancelled' 是常见的取消/作废关键词
            $description = $event->getEventDescription();

            if ($description && (str_contains(strtolower($description), 'voided') || str_contains(strtolower($description), 'cancelled'))) {
                // 找到取消或作废事件
                // 审计事件的描述通常会直接包含取消原因，例如 "Envelope was voided by [User Name] with reason: [Cancellation Reason]"
                // 或者 "Envelope voided with reason: [Cancellation Reason]"
                return $description; // 返回包含原因的完整描述
            }
        }
        return null;
    }
}

// 假设您已在环境变量中配置了这些信息
$accessToken = getenv('DOCUSIGN_ACCESS_TOKEN');
$accountId = getenv('DOCUSIGN_ACCOUNT_ID');
$baseUrl = getenv('DOCUSIGN_BASE_URL');
$envelopeId = 'YOUR_ENVELOPE_ID'; // 替换为你要查询的信封ID

try {
    $auditor = new DocusignEnvelopeAuditor($accessToken, $accountId, $baseUrl);
    $auditEvents = $auditor->getEnvelopeAuditEvents($envelopeId);
    $cancellationReason = $auditor->parseCancellationReason($auditEvents);

    if ($cancellationReason) {
        echo "信封ID: {$envelopeId} 的取消原因: " . $cancellationReason . "\n";
    } else {
        echo "信封ID: {$envelopeId} 未找到明确的取消原因，或信封未被取消。\n";
    }
} catch (\DocuSign\eSign\ApiException $e) {
    echo "DocuSign API调用错误: " . $e->getMessage() . "\n";
    // 根据需要进行更详细的错误处理，例如记录日志或通知管理员
    if ($e->getResponseBody()) {
        echo "错误响应体: " . $e->getResponseBody() . "\n";
    }
} catch (Exception $e) {
    echo "发生未知错误: " . $e->getMessage() . "\n";
}