首页 > 营销学院 > 技术知识

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

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

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

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

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

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

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

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

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

获取审计事件列表

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

察言观数AskTable

企业级AI数据表格智能体平台

72 查看详情察言观数AskTable

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

<?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;
// }

代码说明：

DocusignEnvelopeService 类封装了与DocuSign API交互的逻辑。
getEnvelopeAuditEvents 方法负责初始化DocuSign API客户端并调用EnvelopesApi::getAuditEvents来获取审计事件列表。
getCancellationOrRejectionReason 方法则遍历获取到的审计事件。
关键点： 识别事件类型。你需要查找event->getDescription()（或类似方法）中包含“Voided”（作废）或“Rejected”（拒绝）等关键词的事件。
提取原因： 一旦找到匹配的事件，原因通常会存储在该事件对象的特定字段中，例如getReason()或getVoidReason()。有时，原因也可能嵌入在description字段中，需要通过正则表达式等方式进行解析。请务必查阅DocuSign官方API文档或SDK返回的对象结构，以确定确切的字段名。

注意事项

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

总结

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

以上就是DocuSign API：获取信封取消或拒绝原因的详细教程的详细内容，更多请关注php中文网其它相关文章！

# 未找到 # 荥阳快手短视频营销推广 # 昆明网站建设优化技术 # 无锡市场营销推广招商 # 营销推广公司价值 # 网站建设做排行好吗 # 道真网络营销推广 # 附近网站建设制作公司 # seo网站赚钱秘籍 # 伊春爱采购关键词排名 # 美容整形网站推广 # 这一 # 加密文件 # 字段名 # php # 通常会 # 怎么看 # 您的 # 遍历 # 关键词 # 网络问题 # api调用 # 环境变量 # ai # access # app # 正则表达式

相关栏目：【 Google疑问12 】【 Facebook疑问10 】【优化推广96088 】【技术知识133117 】【 IDC资讯59369 】【网络运营7196 】【 IT资讯61894 】

2025-12-03

SQL多表关联如何理解_核心原理解析助你掌握关键方法【教程】 SQL多表连接如何理解_JOIN关联关系详细步骤解析【指导】 SQL多表连接结果异常怎么办_JOIN条件排查方法解析【指导】 SQL索引下推是什么_ICP机制性能提升原理【教程】 SQL跨表统计怎么写_重要技巧总结提升查询效率【技巧】 SQL注入如何防护_完整逻辑拆解助力系统化掌握【技巧】 SQL上传文件信息建模方法_SQL存储文件元数据方案 SQL多语种存储方案设计_SQL字符集选择策略 SQL字符串处理如何编写_重要技巧总结提升查询效率【教学】 SQL去重查询怎么实现_优化思路讲解帮助高效处理数据【技巧】 SQL统计复购用户怎么做_多次行为分析SQL思路【教程】 SQL字符串处理如何编写_优化思路讲解帮助高效处理数据【教程】 SQL动态字段解析技巧_SQL解析JSON多层字段 SQL线上慢SQL如何治理_规范与工具实践总结【技巧】 SQL表结构如何演进_兼容老数据设计思路【教程】 SQL排序规则如何设置_ORDERBY排序原理与性能说明【指导】 SQL去重查询怎么实现_真实案例解析强化复杂查询思维【教学】 SQL按字段范围分批处理_SQL避免长时间锁表 SQL统计不同字段组合数量_多列聚合查询技巧【技巧】 SQL多字段去重怎么处理_GROUPBY去重思路说明【教学】

了解您产品搜索量及市场趋势，制定营销计划

同行竞争及网站分析保障您的广告效果

点击免费数据支持

提交您的需求，1小时内享受我们的专业解答。

运城市盐湖区信雨科技有限公司

运城市盐湖区信雨科技有限公司是一家深耕海外推广领域十年的专业服务商，作为谷歌推广与Facebook广告全球合作伙伴，聚焦外贸企业出海痛点，以数字化营销为核心，提供一站式海外营销解决方案。公司凭借十年行业沉淀与平台官方资源加持，打破传统外贸获客壁垒，助力企业高效开拓全球市场，成为中小企业出海的可靠合作伙伴。