DocuSign API：如何預填充資料到標籤中，但允許使用者編輯？

導航 DocuSign API：預填充標籤的同時啟用用戶編輯

在數字文檔管理不斷演變的格局中，像 DocuSign 這樣的電子簽名平台已成為企業簡化工作流程的必不可少工具。DocuSign API 以其靈活性脫穎而出，允許開發者自動化和自訂簽名體驗。在將預填充數據集成到文檔中時，會出現一個常見挑戰——確保字段（或 DocuSign 術語中的「tabs」）從外部來源自動填充，但仍可由簽名者編輯，以適應必要的調整。這種平衡提高了效率，同時不損害用戶控制，使其成為金融、地產和人力資源等行業的重要功能。

從業務角度來看，這種功能減少了手動數據輸入錯誤，並加速了合約週期，根據行業報告，可能將處理時間縮短高達 50%。然而，實現需要仔細處理 API，以避免過早鎖定字段。

正在比較帶有 DocuSign 或 Adobe Sign 的電子簽名平台？

eSignGlobal 提供更靈活且性價比更高的電子簽名解決方案，具備全球合規性、透明定價和更快的入職流程。

👉 開始免費試用

掌握 DocuSign API 中的預填充：技術指南

DocuSign eSignature REST API v2.1 提供了強大的工具來管理標籤，這些標籤是文檔上放置的交互元素，如文本框、複選框和日期字段。預填充這些標籤涉及在信封創建期間通過 API 調用注入數據，同時設置屬性以允許簽名者修改。這種方法特別適用於初始數據來自 CRM 系統或表單的場景，但簽名者需要驗證或調整細節。

關鍵概念：標籤及其屬性

DocuSign 中的標籤在 API 負載的 signHere 或 text 對象的 tabs 數組中定義。要預填充，請使用 value 屬性，但要啟用編輯，請確保標籤的 documentId 和 pageNumber 正確對齊，並避免只讀標誌。重要的是，除非通過 locked 或 required 屬性明確設置，否則標籤默認不會鎖定——允許自然的編輯性。

例如，在銷售合約中，您可能從數據庫預填充買家的姓名，但允許在聯繫細節更改時進行更正。這可以防止僵硬的工作流程，這些工作流程會挫敗用戶並導致文檔被放棄。

逐步實施

1. 認證並準備信封： 首先通過 OAuth 2.0 獲取訪問令牌。使用 /envelopes 端點創建信封。將您的文檔作為 base64 編碼的文件上傳，或引用現有模板。

   示例負載片段（JSON）：

   {
     "status": "sent",
     "emailSubject": "Review and Sign Agreement",
     "documents": [
       {
         "documentBase64": "<base64-encoded-PDF>",
         "name": "Contract.pdf",
         "fileExtension": "pdf",
         "documentId": "1"
       }
     ],
     "recipients": {
       "signers": [
         {
           "email": "signer@example.com",
           "name": "John Doe",
           "recipientId": "1",
           "tabs": {
             "textTabs": [
               {
                 "tabLabel": "BuyerName",
                 "documentId": "1",
                 "pageNumber": "1",
                 "xPosition": "100",
                 "yPosition": "200",
                 "width": "150",
                 "height": "20",
                 "value": "Pre-filled Name from API",  // Pre-populates the field
                 "locked": "false",  // Ensures editability
                 "required": "false"  // Optional; set to true if mandatory
               }
             ]
           }
         }
       ]
     }
   }
   

   在這裡，value 屬性注入數據，而 locked: false（默認）允許簽名者編輯。坐標（xPosition、yPosition）在 PDF 上精确定位標籤。

2. 處理基於模板的預填充： 如果使用模板（通過 /templates/{templateId}/envelopes），首先使用 GET 請求提取標籤到 /envelopes/{envelopeId}/documents/{documentId}/tabs。然後，修改響應以添加 value，而不更改 tabLabel 或位置。發送更新的信封。這種方法適用於可重用表單，在注入動態數據的同時保留結構。

3. API 調用執行： 使用 POST 到 /accounts/{accountId}/envelopes 以及負載。像 Node.js 或 Python 的 DocuSign SDK 這樣的庫簡化了這一過程：

   # Python example using docusign-esign library
   from docusign_esign import ApiClient, EnvelopesApi, EnvelopeDefinition
   
   api_client = ApiClient()
   api_client.host = 'https://demo.docusign.net/restapi'  # Use production for live
   envelopes_api = EnvelopesApi(api_client)
   
   envelope_definition = EnvelopeDefinition(
       status='sent',
       email_subject='Please sign',
       documents=[/* your document */],
       recipients=/* with tabs as above */
   )
   
   results = envelopes_api.create_envelope(account_id, envelope_definition)
   

   通過 Webhooks 監控完成情況，確保編輯被捕獲在審計日誌中。

4. 編輯性的最佳實踐：

   • 驗證：在發送前使用 validateTabs 端點檢查標籤放置和數據完整性。
   • 條件邏輯：對於高級情況，通過 API 與 Business Pro 功能集成以應用規則（例如，僅在預填充值滿足條件時顯示可編輯字段）。
   • 錯誤處理：如果預填充失敗（例如，標籤不匹配），API 返回 400 錯誤——記錄這些以進行調試。
   • 測試：始終使用 DocuSign 開發者沙箱。請注意信封配額：Starter API 計劃允許每月約 40 個，隨層級擴展至每年 5,760 美元的高級版。

5. 常見陷阱及解決方案：

   • 過度鎖定：如果標籤顯示不可編輯，請驗證沒有 readOnly 或自訂驗證強制執行。解決方案：在標籤屬性中明確設置 editable: true。
   • 數據覆蓋：簽名者的更改會無縫覆蓋 API 值，但如果需要合規性，請通過 originalValue 跟踪。
   • 多簽名者場景：按 recipientId 分配標籤；僅為相關簽名者預填充以避免混淆。
   • 合規性說明：預填充數據必須符合 ESIGN Act（美國）或 eIDAS（歐盟）等法規，確保審計跟踪捕獲編輯。

此過程對於基本集成通常需要 10-20 分鐘實現，完全自訂會增加複雜性。企業報告實施後簽名速度提高 30-40%，根據 DocuSign 案例研究。

業務環境中的益處

預填充可編輯標籤簡化了入職、貸款申請和供應商協議。例如，在地產中，代理可以從 MLS 數據自動填充買家信息，允許現場調整。它還與 Salesforce 等 CRM 良好集成，減少數據孤島。

DocuSign 及其生態系統概述

DocuSign 自 2003 年以來一直是電子簽名領域的領導者，提供包括 eSignature、CLM（合約生命周期管理）和 API 工具在內的全面套件。其 API 啟用無縫集成，支持超過 1,000 個應用。定價從個人版每月 10 美元開始，擴展到 Business Pro 每月每用戶 40 美元，API 計劃從每年 600 美元起。高級功能如 Bulk Send 和身份驗證會增加計量成本，使其適合需要強大自動化的企業。

DocuSign 的 IAM（身份和訪問管理）通過 SSO 和審計跟踪增強安全性，而 CLM 自動化合約談判、提取和分析——非常適合處理高量合約的法律團隊。

競爭格局：Adobe Sign、eSignGlobal 和 HelloSign

Adobe Sign：面向企業的集成

Adobe Sign 是 Adobe Document Cloud 的一部分，在 PDF 中心工作流程中表現出色，與 Acrobat 深度綁定。它通過類似於 DocuSign 的 API 支持預填充，使用字段標籤進行可編輯填充。定價從個人每月每用戶 10 美元開始，高達團隊每月每用戶 40 美元，企業版自訂報價。優勢包括 AI 驅動的表單填充和移動簽名，但 API 配額對於高量使用可能有限制。它符合 ESIGN 和 eIDAS 等全球標準，適合創意和文檔密集型行業。

eSignGlobal：針對亞太地區的全球玩家

eSignGlobal 將自己定位為多功能替代方案，在全球 100 個主流國家合規，尤其在亞太（APAC）地區表現出色。APAC 的電子簽名格局碎片化，具有高標準和嚴格法規——不同於更基於框架的 ESIGN（美國）或 eIDAS（歐盟）模式，這些模式依賴電子郵件驗證或自我聲明。APAC 要求「生態系統集成」方法，需要與政府到企業（G2B）數字身份的深度硬件/API 集成，這將技術障礙提高到遠高於西方標準的水平。

eSignGlobal 通過對香港 iAM Smart 和新加坡 Singpass 等系統的原生支持來解決這個問題，確保無縫、合規的工作流程。它正在歐洲和美洲積極擴張，以與 DocuSign 和 Adobe Sign 競爭，提供競爭性定價：Essential 計劃每月 16.6 美元，允許發送高達 100 個文檔、無限用戶席位，並通過訪問代碼驗證——在不收取每席位費用的情況下提供高價值合規性。這種模式吸引了金融和人力資源等受監管行業的擴展團隊。

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

eSignGlobal 提供更靈活且性價比更高的電子簽名解決方案，具備全球合規性、透明定價和更快的入職流程。

👉 開始免費試用

HelloSign（現 Dropbox Sign）：面向 SMB 的簡易性

HelloSign 於 2019 年被 Dropbox 收購，專注於用戶友好的簽名，並通過模板支持 API 預填充可編輯字段。它因快速設置和與 Google Workspace 的集成而備受讚譽。定價從免費版（每月 3 個文檔）開始，然後 Essentials 每月 15 美元，高達 Premium 每月每用戶 25 美元。雖然符合 ESIGN/UETA，但它缺乏一些企業級功能如高級 IAM，使其適合小企業，但對於全球合規需求不夠強大。

電子簽名平台的並排比較

此表突出了權衡：DocuSign 在成熟度上領先，而替代方案提供如成本或區域適配等利基優勢。

電子簽名選擇的最終思考

選擇電子簽名平台取決於規模、地區和集成需求。DocuSign 仍是全面 API 驅動工作流程的可靠選擇。對於強調區域合規性的替代方案，尤其在亞太複雜監管環境中的，eSignGlobal 提供平衡且性價比高的選項。根據您的業務優先級評估，以優化效率和遵守性。