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

<?php

require_once(__DIR__ . '/vendor/autoload.php'); // 根据您的项目结构调整

use DocuSign\eSign\Client\ApiClient;
use DocuSign\eSign\Configuration;
use DocuSign\eSign\Api\EnvelopesApi;
use DocuSign\eSign\Model\EnvelopeAuditEvents; // 引入DocuSign SDK的模型

class DocuSignEnvelopeService
{
    private $apiClient;
    private $accountId;
    private $envelopeId;
    private $accessToken;

    public function __construct(string $accessToken, string $accountId, string $envelopeId, string $basePath)
    {
        $this->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 (\DocuSign\eSign\Client\ApiException $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";
// }

?>