DocuSign API：如何获取信封中特定收件人的状态？

了解 DocuSign 信封中的收件人状态

在数字协议快速发展的世界中，跟踪电子签名的进度对于依赖 DocuSign 等平台的企业的至关重要。DocuSign API 为开发者提供了强大的工具，用于自动化和监控工作流程，特别是检查信封中特定收件人的状态。这种功能确保合规性，提高效率，并帮助团队及时响应延误或完成。从销售合同到 HR 入职，知道收件人是否已查看、签署或拒绝文档，可以防止瓶颈并提升用户体验。

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

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

👉 开始免费试用

为什么通过 DocuSign API 跟踪收件人状态？

企业集成 DocuSign 的 API 以简化运营，但一个常见挑战是实时监控单个收件人的操作。在 DocuSign 中，“信封”指的是用于发送一个或多个文档进行签名的容器，可能涉及多个收件人采用顺序或并行路由。收件人的状态——如“已发送”、“已送达”、“已签署”、“已拒绝”或“已作废”——提供了工作流程健康状况的洞察。例如，在多方合同中，如果关键审批人未响应，可以触发自动化通知来督促他们推进。

从商业角度来看，此功能支持可扩展性。处理高容量协议的公司，如金融服务或房地产公司，使用它生成完成率报告，减少手动跟进并最小化错误。根据行业观察，高效的状态跟踪可以将处理时间缩短高达 30%，直接影响收入周期。

逐步指南：使用 DocuSign API 检索收件人状态

要获取信封中特定收件人的状态，您将利用 DocuSign eSignature REST API（版本 2.1 或更高）。此过程需要通过 OAuth 2.0 进行身份验证，以及对 API 端点的基本了解。以下是一个实用演练，假设您拥有开发者账户和 API 访问令牌。

先决条件

• API 凭证：从 DocuSign 开发者中心获取您的集成密钥（Client ID）、密钥和用户 ID。设置 JWT 或 Auth Code Grant 身份验证。
• 工具：使用 Postman、cURL 或编程语言如 Python/Node.js 结合 DocuSign SDK。
• 信封 ID：您需要信封的唯一 ID（通过 API 或 Web 应用创建时生成）。
• 收件人 ID 或电子邮件：通过其角色（例如，“signer1”）或电子邮件识别特定收件人。

步骤 1: 身份验证并获取访问令牌

首先，获取访问令牌。对于 JWT 身份验证（推荐用于服务器到服务器应用）：

curl -X POST "https://account-d.docusign.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=YOUR_JWT_TOKEN"

将 YOUR_JWT_TOKEN 替换为 base64 编码的 JWT 负载。响应包括一个有效期约一小时的 access_token。

步骤 2: 调用 Envelopes:Recipients 端点

使用 GET /envelopes/{envelopeId}/recipients 端点来获取所有收件人的详细信息，包括状态。

• 端点 URL：https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
  • 将 {accountId} 替换为您的 DocuSign 账户 ID。
  • 将 {envelopeId} 替换为目标信封的 ID。
• 标头：
  • Authorization: Bearer {access_token}
  • Accept: application/json

示例 cURL 请求：

curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients" \
  -H "Authorization: Bearer {access_token}"

步骤 3: 解析响应以获取特定收件人

JSON 响应在 recipients.signers 或 recipients.carbonCopies 等下返回收件人数组。通过 email 或 recipientId 查找匹配的收件人。

示例响应片段：

{
  "recipients": {
    "signers": [
      {
        "email": "recipient@example.com",
        "recipientId": "1",
        "status": "signed",
        "signedDateTime": "2025-01-15T10:30:00Z",
        "deliveryStatus": "delivered"
      }
    ]
  },
  "envelopeId": "{envelopeId}"
}

注意的关键字段：

• status：核心指示器（例如，“sent”、“viewed”、“signed”、“declined”、“faxpending”）。
• declineReason：如果被拒绝，则解释原因。
• signedDateTime：操作时间戳。
• errorDetails：遇到的任何问题。

对于特定收件人，在客户端过滤数组。如果您知道 recipientId，可以使用针对性端点：GET /envelopes/{envelopeId}/recipients/{recipientId} 以获取更精确的详细信息。

步骤 4: 处理边缘情况和最佳实践

• 错误处理：注意 HTTP 401（身份验证失败）或 404（无效 ID）。为速率限制（演示账户为 100 次调用/分钟）实现重试。
• 轮询实时更新：状态不会立即更新；每 30-60 秒轮询端点，或使用 DocuSign Connect（Webhook）进行事件驱动通知。
• 安全性：始终使用 HTTPS 并将令牌范围限制为 signature。
• 测试：在演示环境（demo.docusign.net）开始以避免真实成本。生产环境使用 na3.docusign.net 或特定区域 URL。

在代码中，像 Python SDK 这样的库简化了此过程：

from docusign_esign import ApiClient, EnvelopesApi

api_client = ApiClient()
api_client.host = "https://demo.docusign.net/restapi"
api_client.set_default_header("Authorization", f"Bearer {access_token}")

envelopes_api = EnvelopesApi(api_client)
recipients = envelopes_api.get_recipients(account_id, envelope_id)
specific_recipient = next(r for r in recipients.signers if r.email == "recipient@example.com")
print(specific_recipient.status)

这种方法对于与 Salesforce 等 CRM 系统或自定义应用的集成非常高效，允许企业自动化警报或报告仪表板。

商业洞察：电子签名生态系统中的 API 使用

DocuSign 的 API 定价从 Starter 计划的每年 600 美元开始（每月 40 个信封），扩展到高容量需求的自定义企业选项。虽然强大，但需要仔细管理配额——自动化发送如批量操作的上限约为每年 100 个/用户。对于亚太企业，跨境延迟可能会影响 API 响应性，从而促使评估区域替代方案。

比较电子签名平台：DocuSign 和竞争对手

为了提供平衡观点，以下是 DocuSign 与关键竞争对手如 Adobe Sign、eSignGlobal 和 HelloSign（现为 Dropbox 的一部分）的中立比较。该表格基于 2025 年公开数据，突出定价、功能和优势，重点关注 API 功能、合规性和全球企业的可扩展性。

此比较强调 DocuSign 在企业级 API 深度方面的卓越表现，而替代方案提供成本节省或区域优势。

Adobe Sign 以其与创意工具的集成脱颖而出，使其适合营销团队，但其 API 更注重 PDF，而非 DocuSign 的信封焦点模型。

探索替代方案：Adobe Sign、eSignGlobal 和 HelloSign

Adobe Sign 提供类似于 DocuSign 的可靠 API 用于状态跟踪，使用如 /agreements/{agreementId}/participants 端点查询签名者状态。它在文档密集型行业中备受赞誉，但对于复杂路由可能感觉不太敏捷。

eSignGlobal 是亚太市场的新兴参与者，支持 100 个主流国家和地区的全球合规性，在亚太地区具有特别优势。该地区的电子签名格局碎片化，具有高标准和严格法规，需要超出基本验证的内容。与美国和欧盟依赖电子邮件或自我声明的框架式 ESIGN/eIDAS 标准不同，亚太强调“生态系统集成”方法。这涉及与政府到企业 (G2B) 数字身份的深度硬件/API 级集成，提高了远超西方规范的技术壁垒。eSignGlobal 通过原生支持香港的 iAM Smart 和新加坡的 Singpass 等工具来解决此问题，实现无缝、合规的工作流程。定价具有竞争力，其 Essential 计划每月约 24.9 美元（每年 299 美元），允许最多 100 个签名文档、无限用户座位和通过访问代码验证——同时保持高合规性。这使其成为在受监管市场扩展团队的成本效益选项，该公司正在全球范围内积极与 DocuSign 和 Adobe Sign 竞争，提供灵活定价和更快的区域性能。

HelloSign 通过 /agreement/recipients 提供收件人状态的简单 API 调用，与 Dropbox 集成良好用于文件管理。它对小团队友好，但与 DocuSign 相比，缺乏企业自动化深度。

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

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

👉 开始免费试用

电子签名选择的最终思考

对于优先考虑 API 驱动的信封管理精确性的企业，DocuSign 仍是基准。然而，随着需求演变——特别是在多样化地区——中立替代方案如 eSignGlobal 作为 DocuSign 的替代品，提供强大的区域合规性，有效平衡成本和功能。