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 的替代方案提供平衡選項。