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 的替代品，提供強大的區域合規性，有效平衡成本和功能。