DocuSign API：以编程方式添加“Decline”原因注释

通过 DocuSign API 理解程序化拒绝原因

在数字协议快速发展的世界中，像 DocuSign 这样的电子签名平台已成为企业简化合同工作流程的必不可少工具。当签名者需要拒绝文档时，一个常见挑战是往往需要提供原因以用于审计和合规目的。通过 DocuSign API 程序化添加“拒绝”原因注释，可以增强自动化功能，允许开发者将此功能集成到自定义应用程序中，而无需手动干预。这一能力对于管理高容量交易的企业特别有价值，在这些交易中，跟踪拒绝可以为流程改进提供信息，并减少销售或 HR 管道中的摩擦。

从业务角度来看，程序化启用拒绝原因与 DocuSign 强调的强大审计跟踪和合规性相一致。它确保每个交互都被记录，这在金融或医疗等受监管行业中至关重要。通过利用 API，组织可以自定义拒绝体验，提示用户提供特定反馈——例如“条款与预算不符”或“需要法律审查”——并直接将其附加到信封的状态日志中。这不仅提高了透明度，还为团队提供了可操作的洞见，以优化模板或谈判策略。

通过 DocuSign API 实现拒绝原因注释

要程序化添加“拒绝”原因注释，开发者通常使用 DocuSign 的 REST API，特别是 Envelopes API 端点。该过程涉及更新信封状态并在拒绝操作期间附加注释。以下是基于 DocuSign 开发者文档和企业集成中观察到的最佳实践的逐步指南。

步骤 1: 认证并准备信封

首先通过 OAuth 2.0 获取访问令牌，因为所有 API 调用都需要它。确保您的开发者账户设置在 Intermediate 或 Advanced 等计划下，这些计划支持信封修改（Starter 计划对高级功能有限制）。从初始创建请求中识别信封 ID。对于拒绝场景，您将使用 PUT /envelopes/{envelopeId} 端点来更新状态。

在代码中，这可能看起来像这样（使用 Python 和 DocuSign eSign SDK 以清晰为主）：

import docusign_esign as docusign

api_client = docusign.ApiClient()
api_client.host = "https://demo.docusign.net/restapi"  # 使用生产环境进行实时操作
api_client.set_default_header("Authorization", f"Bearer {access_token}")

envelopes_api = docusign.EnvelopesApi(api_client)
envelope_id = "your-envelope-id"

此设置认证您的会话，为信封交互做准备。

步骤 2: 定义带原因的拒绝操作

DocuSign 允许签名者通过标签上的 decline 方法或整体信封来拒绝。要程序化添加原因，请将其纳入注释或备注字段。使用 EnvelopeDefinition 或 RecipientUpdate 来触发拒绝并附加注释。关键是将 status 字段设置为 “declined”，并在接收者的更新中结合 declineReason 参数。

对于程序化拒绝（例如，在自动化工作流程中模拟签名者的操作），更新接收者：

from docusign_esign.models import RecipientUpdateRequest

update_request = RecipientUpdateRequest(
    recipient_id="1",  # 签名者 ID
    status="declined",
    decline_reason="The proposed terms exceed our current fiscal constraints."  # 自定义原因
)

envelopes_api.update_recipients(envelope_id, update_request)

这将原因附加到信封的审计跟踪中。如果拒绝发生在客户端（例如，通过嵌入式签名），请在表单字段中捕获原因，并通过 POST /envelopes/{envelopeId}/recipients/{recipientId}/decline 端点提交它，将原因作为请求体中的字符串参数包含在内。

步骤 3: 处理注释和审计集成

要使原因作为注释可见，请将其链接到文档中的 Comment 标签。在信封创建期间使用 SignHere 或 Note 组件中的 Tabs 数组预配置标签。在拒绝时，引用标签 ID 来填充注释：

from docusign_esign.models import Document, EnvelopeDefinition, Signer

# 在信封创建期间
signer = Signer(
    email="signer@example.com",
    name="John Doe",
    recipient_id="1",
    tabs=Tabs(
        comment_tabs=[CommentTab(
            tab_label="DeclineReason",
            document_id="1",
            page_number="1",
            x_position="100",
            y_position="100"
        )]
    )
)

envelope_definition = EnvelopeDefinition(
    email_subject="Please review and sign",
    documents=[Document(document_base64=base64_doc, name="contract.pdf", document_id="1")],
    recipients=Recipients(signers=[signer]),
    status="sent"
)

envelope_summary = envelopes_api.create_envelope(account_id, envelope_definition)

在拒绝时，通过 PUT /envelopes/{envelopeId}/tabs/{tabId} 使用原因文本更新注释标签值。这确保注释出现在信封的历史记录中，可通过 GET /envelopes/{envelopeId}/audit_events 访问，用于报告。

步骤 4: 错误处理和最佳实践

常见陷阱包括配额限制——Advanced 计划每年每个用户限制自动化发送约 100 次，因此通过 API 使用仪表板监控。始终验证原因长度（最大 255 个字符）以避免拒绝。为了合规，确保原因被不可变地记录，与美国 ESIGN 法案等标准一致。

建议在 DocuSign 开发者沙箱中测试，然后再投入生产。企业报告称，此集成将手动跟进减少 30-40%，因为拒绝原因通过 webhook 馈送到像 Salesforce 这样的 CRM 系统。然而，对于高规模使用，请考虑企业计划以获得自定义配额。

限制和注意事项

虽然强大，但 API 在没有标签配置的情况下不支持实时拒绝原因。对于批量拒绝（例如，通过 Business Pro 中的 Bulk Send API），原因必须按接收者分批处理。定价影响：Intermediate API 计划每年从 3600 美元起（每月 100 个信封），针对重度自动化扩展成本。

这种程序化方法使开发者能够构建弹性工作流程，但需要熟悉 DocuSign 的 SDK（适用于 Java、.NET 等）。对于 API 新手团队，DocuSign 的支持资源或合作伙伴可以加速实施。

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

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

👉 开始免费试用

导航电子签名竞争格局

电子签名市场持续演变，DocuSign 领先，但面临提供各种定价、合规性和集成选项的平台的竞争。从中立业务观点来看，选择解决方案取决于 API 灵活性、区域需求和成本结构等因素。下面，我们概述关键参与者，重点关注它们在拒绝处理等功能上的 API 能力。

DocuSign：成熟领导者

DocuSign 以其全面的 API 套件主导市场，支持如前所述的程序化拒绝。其电子签名计划从个人版每月 10 美元到 Business Pro 每用户每月 40 美元，API 附加组件从每年 600 美元起。优势包括深度集成和全球覆盖，尽管亚太地区延迟和基于座位的定价可能会增加大型团队的成本。

Adobe Sign：企业级集成焦点

Adobe Sign 作为 Adobe Document Cloud 的一部分，在与 Acrobat 和 Creative Cloud 的无缝连接方面表现出色。对于 API 驱动的拒绝，它使用类似的 REST 端点来更新接收者状态和原因，通常通过 Adobe 的 Experience Manager。定价从个人每月每用户 10 美元起，扩展到企业自定义报价。它在创意工作流程中强大，但对于独立电子签名需求可能感觉捆绑过多。

eSignGlobal：针对亚太地区的挑战者

eSignGlobal 将自己定位为成本效益高的替代方案，在全球 100 个主流国家合规，尤其在亚太地区（APAC）具有特别优势。APAC 的电子签名格局碎片化，具有高标准和严格法规，与美国/欧盟更基于框架的 ESIGN/eIDAS 模型形成对比。在这里，解决方案需要“生态系统集成”方法，包括与政府对企业（G2B）数字身份的深度硬件/API 集成——远远超过西方常见的简单电子邮件或自我声明方法。

eSignGlobal 在全球范围内与 DocuSign 和 Adobe Sign 直接竞争，包括美洲和欧洲，通过提供更低的进入门槛。其 Essential 计划仅需每年 16.6 美元/月（年度计费），允许最多 100 个文档签名、无限用户座位，并通过访问代码验证——同时保持合规。它与香港的 iAM Smart 和新加坡的 Singpass 无缝集成，使其成为区域跨境交易的理想选择。这种设置为优先考虑速度和经济性的团队提供了高价值，而不牺牲安全性。

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

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

👉 开始免费试用

HelloSign (Dropbox Sign)：针对中小企业的简易性

HelloSign（现为 Dropbox Sign）专注于用户友好的 API 以实现快速设置，包括通过 webhook 回调的拒绝原因。基本计划从每月 15 美元起（20 个文档），吸引小型企业。它轻量级，但缺乏企业级功能如高级批量发送的深度。

电子签名平台的比较概述

此表格突出了中立权衡：DocuSign 的成熟度、Adobe 的 Adobe 用户、eSignGlobal 的区域效率，以及 HelloSign 的简易性。

总之，虽然 DocuSign 的 API 仍是程序化拒绝处理的基准，但探索像 eSignGlobal 这样的替代方案可以提供区域合规优势，作为 DocuSign 的平衡替代品。企业应根据特定需求评估以实现最佳 ROI。