DocuSign API：如何通过自定义字段值搜索信封？

高效管理 DocuSign API 中的信封导航

在数字签名解决方案的竞争格局中，DocuSign 的 API 脱颖而出，成为开发者和企业自动化工作流程的强大工具。一个常见挑战是根据自定义元数据检索特定信封——DocuSign 对文档包的称呼。这种能力对于处理大量协议的企业至关重要，能够实现针对性搜索而无需手动筛选。从商业角度来看，掌握此类 API 功能可以简化合规审计、销售跟踪和客户支持，从而最终降低运营成本。

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

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

👉 开始免费试用

理解 DocuSign API 中的信封和自定义字段

DocuSign 信封代表电子签名的核心单元，封装了文档、收件人和签名字段。自定义字段，也称为文本或标签字段，允许用户直接将元数据（如合同 ID、客户名称或状态标签）嵌入信封中。这些字段不仅仅用于显示；它们支持程序化查询，这对于 CRM 系统或自定义仪表板的集成非常宝贵。

从商业角度来看，利用自定义字段进行搜索可以提升数据治理。受监管行业的企业，如金融或医疗保健，可以使用它们根据合规标记过滤信封，确保审计期间快速访问。DocuSign 的 API 是其开发者平台的一部分，通过 RESTful 端点支持此功能，定价层级如 Intermediate 计划（每年 3,600 美元）为此类操作提供每月高达 100 个信封。

逐步指南：根据自定义字段值搜索信封

要通过 DocuSign API 使用自定义字段值搜索信封，您需要一个活跃的开发者账户和 API 凭证。此过程假设您使用 eSignature REST API v2.1，这是 2025 年的当前标准。以下是基于官方文档的中性、实用演练。

先决条件和设置

1. 获取 API 访问权限：在 developer.docusign.com 注册 DocuSign 开发者沙箱。生成集成密钥（客户端 ID）和密钥用于 OAuth 认证。对于生产环境，升级到付费计划——Starter 计划（每年 600 美元）适合基本搜索。

2. 定义自定义字段：在创建信封时，通过 API 添加自定义字段。在信封定义中使用 customFields 对象。例如：

   {
     "status": "sent",
     "emailSubject": "Agreement for Review",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   这将 “CLI-12345” 嵌入为 “ClientID” 字段下的可搜索值。

3. 认证：使用 JWT 或 Auth Code Grant 流程。在 Python 中（使用 requests 库）的示例 JWT 请求如下：

   import requests
   import jwt
   import time
   
   def get_jwt_token(integration_key, user_id, rsa_key, account_id):
       claim = {
           "iss": integration_key,
           "sub": user_id,
           "aud": "account-docusigncom",
           "iat": int(time.time()),
           "exp": int(time.time()) + 3600,
           "scope": "signature impersonation"
       }
       token = jwt.encode(claim, rsa_key, algorithm='RS256')
       response = requests.post(
           "https://account-docusign.com/oauth/token",
           headers={"Authorization": f"Bearer {token}"},
           data={
               "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
               "assertion": token
           }
       )
       return response.json()["access_token"]
   

   用您的凭证替换占位符。此令牌用于认证后续 API 调用。

执行搜索

关键端点是 GET /accounts/{accountId}/envelopes/search，但对于自定义字段过滤，请结合查询参数或使用更灵活的 GET /envelopes 带搜索标准。DocuSign 的搜索 API 允许通过 searchText 参数按自定义字段查询，该参数匹配信封元数据，包括自定义值。

• 基本搜索端点：使用 GET /accounts/{accountId}/envelopes?search_text={value}。这会扫描信封主题、名称和自定义字段。

  对于精确的自定义字段匹配，请利用高级搜索中的 query 参数。然而，直接自定义字段查询需要 Envelopes: listStatusChanges 或类似权限。

  示例 cURL 请求：

  curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes?search_text=CLI-12345" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"
  

  响应片段：

  {
    "envelopes": [
      {
        "envelopeId": "abc-123-def",
        "status": "completed",
        "customFields": {
          "textCustomFields": [
            {
              "name": "ClientID",
              "value": "CLI-12345"
            }
          ]
        }
      }
    ]
  }
  

• 使用自定义字段的高级过滤：对于特定信封搜索，首先检索日期范围或状态内的信封，然后在客户端过滤。DocuSign 建议结合 fromDate 和 toDate 参数与 search_text 使用以提高效率。如果您的量超过配额（例如 Intermediate 计划每月 100 个信封），考虑升级到 Advanced（每年 5,760 美元）以获得批量功能。

  在代码中，解析响应以匹配确切自定义字段值：

  import json
  
  response = requests.get(
      f"https://demo.docusign.net/restapi/v2.1/accounts/{account_id}/envelopes",
      headers={
          "Authorization": f"Bearer {access_token}",
          "Accept": "application/json"
      },
      params={"search_text": "CLI-12345", "from_date": "2025-01-01T00:00:00Z"}
  )
  envelopes = response.json()["envelopeSummary"]["envelopes"]
  matching_envelopes = [
      env for env in envelopes
      if any(cf["name"] == "ClientID" and cf["value"] == "CLI-12345" for cf in env.get("customFields", {}).get("textCustomFields", []))
  ]
  print(json.dumps(matching_envelopes, indent=2))
  

最佳实践和限制

• 配额和成本：搜索计入信封 API 限制。超过将产生超额费用或需要 Enterprise 定制。
• 安全性：始终使用 HTTPS 和基于角色的访问权限，以防止未经授权的查询。
• 错误处理：常见问题包括 401（无效令牌）或 400（无效查询）。记录响应以进行调试。
• 可扩展性：对于高容量搜索，请与 DocuSign 的 Connect webhook 集成以推送更新，减少轮询需求。

此 API 功能将 DocuSign 定位为自动化合规的领导者，尽管企业应评估总成本，包括附加组件如身份验证。

DocuSign：电子签名解决方案的市场领导者

DocuSign 自 2004 年以来一直是电子签名的先驱，提供全面的文档管理工具。其电子签名平台包括从 Personal（每年 120 美元）到 Business Pro（每年 480 美元/用户）的计划，API 访问通过独立的开发者计划。关键功能包括模板、批量发送以及与 400 多个应用的集成。对于高级需求，DocuSign 的 Intelligent Agreement Management (IAM) 将 CLM（合同生命周期管理）与 AI 驱动的洞察相结合，自动化修订和风险评估。IAM 适合企业，尽管定价为自定义的，并可能随着席位和信封数量而增加。

Adobe Sign：企业工作流程的强大集成

Adobe Sign 是 Adobe Document Cloud 的一部分，在与 PDF 工具和创意套件的无缝集成方面表现出色。定价从个人每月约 10 美元/用户开始，扩展到企业自定义计划。它支持类似于 DocuSign 的自定义字段和 API 搜索，使用如 /agreements 的端点查询元数据。优势包括强大的 Adobe 生态系统联系和全球合规，但高级 API 功能可能需要额外许可。企业重视其在签名旁边的文档创作重点。

eSignGlobal：针对 APAC 和全球合规的定制解决方案

eSignGlobal 作为一家专业玩家脱颖而出，特别是在亚太（APAC）地区，那里的电子签名法规碎片化、高标准且严格监管。与美国 ESIGN/UETA 或欧洲 eIDAS 的框架——依赖电子邮件验证或自我声明——不同，APAC 要求生态系统集成的标准。这涉及与政府对企业（G2B）数字身份的深度硬件/API 级对接，将技术壁垒显著提高到高于西方模式。eSignGlobal 通过覆盖 100 个主流全球国家和地区的合规来应对此问题，通过香港和新加坡的本地数据中心在 APAC 占据优势。它支持与香港 iAM Smart 和新加坡 Singpass 等无缝集成，以实现强大的身份验证。定价具有竞争力，Essential 计划每年 299 美元（年化相当于每月约 16.6 美元），允许最多 100 个签名文档、无限用户席位和访问代码验证——所有这些基于合规、成本效益的基础，低于许多竞争对手，同时保持法律效力。

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

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

👉 开始免费试用

HelloSign (Dropbox Sign)：SMB 的简易解决方案

HelloSign，现为 Dropbox Sign，优先考虑中小企业的用户友好界面。免费版每月最多三个文档，付费计划从每月 15 美元开始。其 API 支持通过自定义字段的信封搜索，使用如 /templates 和 /signatures 的端点，尽管不如 DocuSign 细粒度。适合与 Dropbox 的快速集成，重点在于易用性而非企业级定制。

电子签名平台的比较概述

此表格突出了中性的权衡；选择取决于区域需求和规模。

总之，虽然 DocuSign 的 API 赋能精确的信封搜索，但探索替代方案可以针对特定市场优化。对于区域合规，eSignGlobal 作为 DocuSign 的替代方案提供平衡选项。