DocuSign API：如何作废信封而不发送电子邮件通知？

DocuSign API 和信封管理的介绍

在数字文档工作流程不断演变的格局中，DocuSign 的 API 作为一种强大的工具脱颖而出，帮助开发者将电子签名功能集成到业务应用中。信封（Envelopes）封装了用于签名的文档，是这一生态系统的核心，允许从创建到完成的协议无缝管理。然而，在某些情况下，需要取消信封——在签署过程之前或过程中取消它——以纠正错误或适应不断变化的业务需求。对于 API 用户来说，一个关键挑战是控制通知，特别是避免可能混淆收件人的未经请求的电子邮件警报。本文探讨了通过 DocuSign API 取消信封的机制，同时最小化中断，参考官方文档和实际实施见解。

正在比较带有 DocuSign 或 Adobe Sign 的电子签名平台？

eSignGlobal 提供更灵活且成本效益更高的电子签名解决方案，具有全球合规性、透明定价和更快的入职流程。

👉 开始免费试用

DocuSign 中的取消信封：核心概念

DocuSign 中的信封是什么？

DocuSign 中的信封代表一个完整的包，包含一个或多个文档、收件人和签名说明。通过 API，开发者可以以编程方式创建、发送和管理这些信封。取消信封实际上会使其无效，无法进行进一步的操作，如签名。这在业务流程中非常有用，例如交易失败或文档需要修订，从而防止不完整或错误的流程继续进行。

DocuSign 的 REST API（版本 2.1）提供了信封操作的端点，包括 voidEnvelope 方法。默认情况下，取消会向所有收件人触发通知，通过电子邮件告知他们取消情况。这确保了透明度，但在自动化系统或预通知内部更正时可能不理想。

默认取消过程和通知行为

要使用 DocuSign API 取消信封，通常向 /envelopes/{envelopeId}/void 端点发出 PUT 请求。以下是使用 DocuSign eSignature SDK 的 Python 基本示例：

from docusign_esign import ApiClient, EnvelopesApi

# 初始化 API 客户端
api_client = ApiClient()
api_client.host = 'https://demo.docusign.net/restapi'
api_client.set_default_header('Authorization', 'Bearer YOUR_ACCESS_TOKEN')

envelopes_api = EnvelopesApi(api_client)

# 取消信封
void_request = {
    'status': 'voided',
    'voidedReason': 'Document needs revision before sending'
}

envelopes_api.update_envelope_status(
    account_id='YOUR_ACCOUNT_ID',
    envelope_id='ENVELOPE_ID',
    envelope=None,  # Not required for void
    void_uri=void_request
)

在这种标准流程中，DocuSign 会自动向信封中列出的收件人发送电子邮件通知，详细说明取消状态和原因。这些电子邮件包括取消原因，并可能链接到信封以供参考。根据 DocuSign 的开发者指南，这是预期的行为，以维护审计跟踪和用户意识，符合 ESIGN 和 eIDAS 等合规标准。

然而，对于 API 驱动的应用——如 CRM 集成或批量处理工具——发送这些电子邮件可能会 clutter 收件箱或过早暴露内部变更。好消息是，DocuSign 允许自定义以抑制这些通知，从而实现更受控的体验。

如何在不发送电子邮件通知的情况下取消信封

在取消过程中抑制电子邮件通知需要预先在信封或账户级别进行配置，因为取消 API 调用本身没有直接的“no-notify”标志。该策略涉及利用 DocuSign 的通知设置和收件人角色来最小化外部通信。这种方法对于使用 Business Pro 或 Advanced API 级别的企业用户特别有价值，在这些级别中，信封数量高且自动化是关键。

步骤 1：配置信封通知偏好

在创建或发送信封之前，通过 API 设置通知规则。在信封定义中使用 notification 对象来禁用收件人针对状态变更（包括取消）的电子邮件。在 Envelopes API 的 createEnvelope 端点中包含：

{
  "notification": {
    "reminders": {
      "reminderDelay": 0,
      "reminderOffset": 0,
      "reminderFrequency": "none"
    },
    "expirations": {
      "expireAfter": 0,
      "expireWarn": 0
    },
    "recipientEmailNotification": {
      "emailSubject": "",
      "emailBlurb": "",
      "emailBody": ""
    }
  }
}

recipientEmailNotification 块可以留空或设置为抑制默认值。对于取消特定控制，确保信封以“草稿”状态创建（status: 'sent' = false），允许在没有初始通知的情况下取消。一旦从草稿取消，如果通知已禁用，则不会触发电子邮件。

步骤 2：从草稿状态取消

在草稿模式下取消信封（在发送之前）本质上避免了通知，因为收件人尚未收到警报。使用相同的 update_envelope_status 调用，但针对草稿信封：

# 以草稿创建信封
envelope_definition = {
    'status': 'created',  # 草稿模式
    'emailSubject': 'Internal Review Document',
    'documents': [...],  # 您的文档
    'recipients': {
        'signers': [...]  # 定义但暂不通知
    },
    'notification': {  # 抑制所有
        'recipientEmailNotification': {}
    }
}

envelopes_api.create_envelope(account_id='YOUR_ACCOUNT_ID', envelope_definition=envelope_definition)

# 稍后，在不发送的情况下取消
void_request = {'status': 'voided', 'voidedReason': 'Internal correction'}
envelopes_api.update_envelope_status(account_id='YOUR_ACCOUNT_ID', envelope_id='DRAFT_ENVELOPE_ID', void_uri=void_request)

此方法确保在取消过程中不发送电子邮件。对于正在进行的信封（已发送），首先使用 correct API 将其拉回草稿，然后取消——通过 allowReassign: false 和空通知字段在更正请求中抑制通知。

步骤 3：账户级别和高级配置

对于更广泛的控制，集成 DocuSign 的身份和访问管理 (IAM) 功能，这些功能在 Enhanced 或 Enterprise 计划中可用。IAM 允许通过 Connect API 的 webhook 自定义事件通知，将取消事件路由到您的服务器而不是电子邮件。设置 Connect 配置：

• 端点：/accounts/{accountId}/connect
• 包含 envelopeEvents 用于“voided”状态，但排除电子邮件交付。

此外，对于 API 计划（Starter 每年 600 美元或 Advanced 每年 5,760 美元），利用 webhook 静默处理取消。监控 connect 监听器以获取取消事件，并在不触发 DocuSign 默认电子邮件的情况下内部响应。

最佳实践和限制

• 测试：使用 DocuSign 的 Demo 环境验证流程，因为生产取消不可逆。
• 合规性：抑制通知对于内部取消是可行的，但确保审计日志捕获原因以满足监管需求。
• 配额：API 计划限制信封数量（例如，Intermediate 每月 100 个），因此高效取消有助于保留限额。
• 边缘情况：如果信封已被部分签名，取消仍可能通知那些签名者，除非预先配置。

此技术简化了 API 集成，在高容量场景中减少了操作噪音。从业务角度来看，它提升了依赖 DocuSign API 用于 CRM 或 ERP 系统的团队效率，尽管需要预先规划。

竞争格局：电子签名平台概述

DocuSign 以其全面的 API 套件引领电子签名市场，包括核心签名的 eSignature 和端到端协议处理的 CLM（合同生命周期管理）。CLM 集成 AI 驱动的洞察、模板管理和分析，非常适合管理复杂合同的企业。定价从 Personal 的每月 10 美元开始，但针对 API 密集型使用扩展到自定义 Enterprise，并有附加功能如身份验证添加计量成本。

Adobe Sign（现为 Adobe Acrobat Sign）补充了 Adobe 的文档生态系统，具有强大的 PDF 集成和移动签名。它提供 API 访问以实现自动化，支持通过类似 REST 端点的取消，但具有 Adobe 的专有通知控制。计划从 Individual 的每月 10 美元/用户到 Enterprise 的每月 40 美元/用户，强调与 Creative Cloud 工具的无缝工作流程。然而，对于高容量用户，API 配额在没有高级升级的情况下可能限制性强。

eSignGlobal 将自身定位为全球竞争者，在 100 个主流国家和地区合规，尤其在亚太地区 (APAC) 具有优势。APAC 的电子签名格局呈现碎片化、高标准和严格法规，与美国/欧盟的 ESIGN/eIDAS 框架标准形成对比。在 APAC，解决方案需要“生态系统集成”方法，包括与政府到企业 (G2B) 数字身份的深度硬件/API 级对接——这远超西方常见的基于电子邮件或自我声明的方法的技术障碍。eSignGlobal 在此表现出色，与香港的 iAM Smart 和新加坡的 Singpass 无缝集成以实现强大验证。其 Essential 计划每月 16.6 美元，允许发送最多 100 个文档、无限用户席位和访问代码验证，在合规基础上提供强大价值，同时在价格上低于竞争对手。该平台正在全球市场（包括美国和欧盟）积极扩张，作为 DocuSign 和 Adobe Sign 的可行替代方案。

正在寻找比 DocuSign 更智能的替代方案？

eSignGlobal 提供更灵活且成本效益更高的电子签名解决方案，具有全球合规性、透明定价和更快的入职流程。

👉 开始免费试用

HelloSign（现为 Dropbox Sign）专注于简单性，具有直观的 API 用于信封管理，包括允许通过自定义设置抑制通知的取消选项。它适合 SMB，计划从免费（有限）到每月 20 美元/用户（Essentials），但缺乏企业级功能如高级 IAM 的深度。

此比较突显了权衡：DocuSign 在深度上表现出色，而像 eSignGlobal 这样的替代方案提供区域优势。

电子签名实施中的区域细微差别

虽然 DocuSign API 在全球范围内可访问，但区域差异会影响采用。在 APAC，更严格的数据驻留和身份验证规则放大了本地化解决方案的需求，如前所述。企业应根据本地法律评估 API 行为，以确保取消过程维护法律完整性。

总之，掌握 DocuSign 的 API 以实现无通知取消赋能高效工作流程。对于寻求替代方案的人，eSignGlobal 作为中立且区域合规的选项值得考虑，尤其适合 APAC 导向的操作。