如何在DocuSign嵌入式电子签名中动态添加签名标签？

方法1：文本锚点（Text Anchor）精准定位 #

如果文档内存在固定的签名提示文本（比如“请在此处签名”“Signature”等），可以用文本锚点自动定位标签，适配不同文档的签名位置：

核心逻辑 #

在创建信封的API请求中，给签名标签配置anchorString（待匹配的提示文本）、anchorUnits（单位，如"pixels"或"percent"）、anchorXOffset/anchorYOffset（相对于锚点文本的偏移量），DocuSign会自动扫描文档匹配文本并放置标签。

原生Java请求示例（无需SDK） #

// 构建信封请求JSON
String envelopeJson = "{" +
  "\"emailSubject\": \"请签署文档\"," +
  "\"documents\": [" +
    "{" +
      "\"documentId\": \"1\"," +
      "\"name\": \"待签文档.pdf\"" +
    "}" +
  "]," +
  "\"recipients\": {" +
    "\"signers\": [" +
      "{" +
        "\"email\": \"signer@example.com\"," +
        "\"name\": \"签名人\"," +
        "\"clientUserId\": \"123\"," + // 嵌入式签署必填参数
        "\"tabs\": {" +
          "\"signHereTabs\": [" +
            "{" +
              "\"anchorString\": \"请在此处签名\"," +
              "\"anchorUnits\": \"pixels\"," +
              "\"anchorXOffset\": \"20\"," +
              "\"anchorYOffset\": \"0\"" +
            "}" +
          "]" +
        "}" +
      "}" +
    "]" +
  "}," +
  "\"status\": \"sent\"" +
"}";

// 发送POST请求到DocuSign API
HttpURLConnection conn = (HttpURLConnection) new URL("https://demo.docusign.net/restapi/v2.1/accounts/your_account_id/envelopes").openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("Authorization", "Bearer your_access_token");
conn.setDoOutput(true);
try (OutputStream os = conn.getOutputStream()) {
    byte[] input = envelopeJson.getBytes("utf-8");
    os.write(input, 0, input.length);
}
// 后续处理响应逻辑省略

方法2：允许用户手动调整标签位置 #

如果无法通过锚点匹配，可以让用户在嵌入式签署界面手动调整标签位置，只需在创建收件人视图时开启编辑权限：

关键参数配置 #

请求收件人视图（POST /v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient）时，添加以下核心参数：

{
  "returnUrl": "https://your_app.com/sign_complete",
  "clientUserId": "123",
  "authenticationMethod": "email",
  "allowEdit": true,
  "enableTabEditing": true
}

用户打开签署链接后，可直接拖动签名标签到正确位置再完成签署。

方法3：模板匹配（针对有限文档类型） #

如果你的文档类型是固定的几种（比如示例中的4种表单），可以提前在DocuSign控制台创建对应模板，预设好签名标签位置，再根据上传的文档类型动态调用模板：

核心步骤 #

1. 在DocuSign控制台创建模板，上传对应文档并放置签名标签，记录每个模板的templateId；
2. 应用内通过文件名、内容特征识别上传的文档类型；
3. 调用API创建信封时引用对应模板ID：

String envelopeJson = "{" +
  "\"emailSubject\": \"请签署文档\"," +
  "\"templateId\": \"your_template_id\"," +
  "\"templateRoles\": [" +
    "{" +
      "\"email\": \"signer@example.com\"," +
      "\"name\": \"签名人\"," +
      "\"clientUserId\": \"123\"," +
      "\"roleName\": \"Signer\"" // 模板中定义的角色名
    "}" +
  "]," +
  "\"status\": \"sent\"" +
"}";

注意事项 #

• 文本锚点匹配时，确保anchorString与文档内文本完全一致（注意大小写、空格）；
• 嵌入式签署必须设置clientUserId，且需与收件人视图请求中的值一致；
• 旧Java环境下，建议使用Apache HttpClient或OkHttp简化HTTP请求处理。

内容的提问来源于stack exchange，提问作者Sam