DocuSign API：获取信封取消或拒绝原因的详细教程

<?php

namespace App\Services;

use DocuSign\eSign\Api\EnvelopesApi;
use DocuSign\eSign\Client\ApiClient;
use DocuSign\eSign\Configuration;
use Exception;

class DocusignEnvelopeService
{
    private $token;
    private $envelope_id;
    private $account_id;

    public function __construct(string $token, string $envelope_id, string $account_id)
    {
        $this->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;
// }