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 提供平衡且性价比高的选项。根据您的业务优先级评估，以优化效率和遵守性。