DocuSign API：生成带有特定过期时间的嵌入式签名 URL

导航 DocuSign 的 API 以实现安全的嵌入式签名

在数字协议不断演变的格局中，企业越来越依赖电子签名平台来简化工作流程，同时确保安全性和合规性。DocuSign 作为该领域的领导者，提供强大的 API 功能，允许开发者将签名流程直接集成到应用程序中。其中一个关键功能是生成嵌入式签名 URL，这使得用户无需离开主机应用程序即可签署文档。本文探讨了如何使用 DocuSign 的 API 实现这一点，重点关注设置特定过期时间以增强控制。从商业角度来看，此类集成可以减少客户入职和合同执行中的摩擦，据行业基准，可能将转化率提高高达 30%。

嵌入式签名在现代业务流程中的作用

嵌入式签名允许文档在 iframe 或 Web 视图中呈现，从而创建无缝的用户体验。与远程签名不同，后者要求收件人通过电子邮件访问链接，嵌入式签名非常适合应用内场景，如销售门户或 HR 系统。DocuSign 的 API 通过其 eSignature REST API 支持这一功能，实现对签名仪式的程序化控制。企业重视这一点，因为它能够保持品牌一致性并收集实时完成事件。

为这些 URL 设置过期时间增加了一层安全性，防止在定义时期后发生未经授权的访问。这在金融或法律等高风险行业特别有用，在这些行业中，时间敏感的文档必须防范重放攻击或无限期暴露。

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

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

👉 开始免费试用

使用 DocuSign API 实现嵌入式签名 URL

要生成带有特定过期的嵌入式签名 URL，开发者必须通过 OAuth 2.0 进行身份验证，并与 DocuSign 的 Envelopes API 交互。此过程涉及创建信封、准备签名，然后检索用于嵌入的临时 URL。从商业角度来看，掌握此功能可以通过自动化手动跟进并与 Salesforce 等 CRM 工具集成来降低运营成本。

步骤 1: 身份验证和信封创建

首先，使用 DocuSign 的 JWT 或授权码授权流程获取访问令牌。此令牌授予 API 访问权限，最长可达 8 小时，之后必须刷新。

使用 /accounts/{accountId}/envelopes 端点创建信封。以下是通过 POST 的 JSON 格式示例请求：

{
  "emailSubject": "Please sign this document",
  "documents": [
    {
      "documentBase64": "base64-encoded-document-content",
      "name": "Agreement.pdf",
      "fileExtension": "pdf",
      "documentId": "1"
    }
  ],
  "recipients": {
    "signers": [
      {
        "email": "signer@example.com",
        "name": "John Doe",
        "recipientId": "1",
        "routingOrder": "1"
      }
    ]
  },
  "status": "sent"
}

这将创建一个带有单个签名者的基本信封。status: "sent" 会立即启动工作流程。

步骤 2: 添加签名字段和嵌入式收件人

对于嵌入式签名，通过包含 clientUserId 和身份验证细节将收件人指定为嵌入式。更新收件人：

"signers": [
  {
    "email": "signer@example.com",
    "name": "John Doe",
    "recipientId": "1",
    "routingOrder": "1",
    "clientUserId": "unique-client-id-123",
    "userId": "signer-user-id",
    "authenticationMethod": "none",  // 或 "email" 以增加安全性
    "embedUrlEvents": {
      "url": "https://your-app.com/return-url"
    }
  }
]

clientUserId 将会话绑定到您的应用程序，确保签名者在您的环境中得到身份验证。

接下来，使用 /envelopes/{envelopeId}/recipients/{recipientId}/tabs 端点定义签名字段。对于简单的签名字段：

{
  "signHereTabs": [
    {
      "documentId": "1",
      "pageNumber": "1",
      "xPosition": "100",
      "yPosition": "200",
      "width": "200",
      "height": "50",
      "recipientId": "1"
    }
  ]
}

这会在文档上放置一个签名标签。

步骤 3: 生成带有过期的嵌入式签名 URL

核心步骤是调用 /accounts/{accountId}/envelopes/{envelopeId}/views/recipient 端点以获取签名 URL。指定 returnUrl 用于签名后重定向，并通过查询参数或信封设置设置过期时间。

示例 GET 请求：

GET /accounts/{accountId}/envelopes/{envelopeId}/views/recipient?email=signer@example.com&userName=John%20Doe&returnUrl=https://your-app.com/complete

响应包括一个带有嵌入式签名链接的 url 字段，默认有效期为 5 分钟。要自定义过期时间，请在创建时使用信封的 expireAfter 属性（以天为单位），或在高级配置中使用 API 的 expireEnabled 和 expireAfterDays。对于粒度控制，请与 DocuSign 的 Event Notifications 集成，以在过期后监控和撤销访问。

在代码中（使用 requests 库的 Python 示例）：

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

# Create envelope (as above)
envelope_response = requests.post(f'{base_url}/envelopes', json=envelope_data, headers=headers)
envelope_id = envelope_response.json()['envelopeId']

# Get embedded URL
url_params = {
    'email': 'signer@example.com',
    'userName': 'John Doe',
    'returnUrl': 'https://your-app.com/complete'
}
url_response = requests.get(f'{base_url}/envelopes/{envelope_id}/views/recipient', params=url_params, headers=headers)
signing_url = url_response.json()['url']

此 URL 现在可以嵌入到 iframe 中：<iframe src="{signing_url}" width="100%" height="600px"></iframe>。过期时间确保链接在设置时间后失效，通常由服务器端强制执行以防止篡改。

最佳实践和商业考虑

从商业观察来看，实现过期时间可以减少受监管行业的责任。通过 DocuSign 的仪表板监控 API 使用情况，以避免配额限制——Starter 计划每月上限 40 个信封，而 Advanced 计划每年 5760 美元提供更多。在沙箱模式下测试，以确保符合美国的 ESIGN/UETA 或欧盟的 eIDAS。常见陷阱包括 clientUserId 不匹配导致身份验证失败，或忽略 returnUrl 影响用户流程连续性。

企业报告称，带有过期的嵌入式签名可以将签名时间缩短 50%，提升客户满意度。然而，API 成本随使用量增加，因此评估替代方案以实现成本效率至关重要。

比较领先的电子签名平台

在选择电子签名解决方案时，API 灵活性、定价和区域合规性等因素起着关键作用。以下是基于 2025 年公开数据的 DocuSign、Adobe Sign、eSignGlobal 和 HelloSign（现为 Dropbox Sign）的中性比较。该表格突出了关键差异，以支持明智决策。

此比较突显了 DocuSign 在企业集成方面表现出色，但价格较高，而其他平台在特定领域提供价值。

DocuSign 以其成熟的 API 生态系统脱颖而出，在全球数千个应用程序中驱动嵌入式签名。其开发者计划从基础版每年 600 美元到自定义企业选项不等，强调高容量企业的可扩展性。

Adobe Sign 与创意和文档工作流程深度集成，通过其 API 提供嵌入式签名，过期选项与信封生命周期相关联。定价起价较高，但与 Acrobat 捆绑适合 PDF 密集型用户。

eSignGlobal 在 100 个主流全球国家提供合规的电子签名，在亚太（APAC）地区具有强大优势。APAC 的电子签名格局呈现碎片化、高标准和严格监管，与西方的 ESIGN/eIDAS 框架形成对比。APAC 要求“生态系统集成”方法，包括与政府数字身份（G2B）的深度硬件/API 集成，远超美国/欧盟常见的电子邮件或自我声明方法。eSignGlobal 通过实惠定价与 DocuSign 和 Adobe Sign 直接竞争——其 Essential 计划每月 16.6 美元，允许发送最多 100 个文档、无限用户席位，以及签名访问码验证。它无缝集成香港的 iAM Smart 和新加坡的 Singpass，以竞争对手成本的一小部分确保区域合规性。

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

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

👉 开始免费试用

HelloSign（现为 Dropbox Sign）在其嵌入式 URL API 中优先考虑简单性，过期通过文档设置处理。它对小团队成本效益高，但缺乏 DocuSign 自动化的深度。

结论：为您的业务选择合适的解决方案

总之，DocuSign 的 API 用于生成带有特定过期的嵌入式签名 URL，为安全、集成的工作流程提供了强大的控制。企业应权衡 API 成熟度与总拥有成本以及区域需求。对于优先考虑 APAC 合规性的企业，eSignGlobal 作为 DocuSign 的中性、区域优化的替代方案脱颖而出。