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

<?php

namespace App\Services; // 假设在一个服务类中

use DocuSign\eSign\Api\EnvelopesApi;
use DocuSign\eSign\Client\ApiClient;
use DocuSign\eSign\Configuration;
use DocuSign\eSign\Client\ApiException; // 引入DocuSign API异常

class DocusignEnvelopeService
{
    private string $token;
    private string $envelopeId;
    private ApiClient $apiClient;
    private EnvelopesApi $envelopesApi;

    /**
     * 构造函数，初始化DocuSign API客户端。
     *
     * @param string $token DocuSign OAuth2访问令牌
     * @param string $envelopeId 目标信封的ID
     */
    public function __construct(string $token, string $envelopeId)
    {
        $this->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);
        }
    }
}