如何通过API在DocuSign模板中动态添加签署人及签名/文本标签

1. 从数据库动态加载签署人并创建对应标签 #

先从数据库拉取签署人列表（包含姓名、邮箱、角色等信息），然后在API请求中构建templateRoles数组（匹配模板角色）或signers数组，每个签署人对象内定义所需的signHereTabs、textTabs等标签：

{
  "emailSubject": "请签署协议",
  "templateId": "你的模板ID",
  "templateRoles": [
    // 遍历数据库返回的签署人列表生成每个节点
    {
      "email": "signer1@example.com",
      "name": "签署人1",
      "roleName": "模板预设角色名", // 模板无预设则自定义
      "tabs": {
        "signHereTabs": [
          {
            "documentId": "1",
            "pageNumber": "1",
            "xPosition": "100",
            "yPosition": "200"
          }
        ],
        "textTabs": [
          {
            "documentId": "1",
            "pageNumber": "1",
            "xPosition": "100",
            "yPosition": "150",
            "value": "签署人1", // 从数据库获取的姓名
            "locked": "true" // 可选：锁定不让修改
          }
        ]
      }
    }
    // 更多签署人节点...
  ],
  "status": "sent"
}

2. 动态创建包含签署人和标签的信封 #

基于现有模板创建信封时，核心是通过templateRoles将数据库签署人映射到模板（无预设角色则用signers数组），同时在每个签署人节点嵌入动态标签。调用DocuSign的Envelopes::create接口，请求体参考上述示例，注意：

• 模板已有固定标签时，可通过tabs字段覆盖或新增
• status设为sent立即发送，设为created保存为草稿

3. 精确设置SignHereTab位置，实现顺序签署 #

方式一：坐标定位 #

直接指定标签在文档上的像素坐标，配合pageNumber和documentId锁定位置：

"signHereTabs": [
  {
    "documentId": "1",
    "pageNumber": "1",
    "xPosition": "150",
    "yPosition": "300",
    "recipientId": "1" // 关联对应签署人ID
  }
]

方式二：锚点文本定位（更灵活） #

在模板文档中插入锚点标记（如[[签署人1签名处]]），API中通过anchorString匹配标记自动定位：

"signHereTabs": [
  {
    "documentId": "1",
    "anchorString": "[[签署人1签名处]]",
    "anchorYOffset": "0",
    "anchorXOffset": "10",
    "anchorUnits": "pixels"
  }
]

实现顺序签署 #

按签署顺序排列templateRoles/signers数组，DocuSign默认按数组顺序发起请求；也可通过*routingOrder*字段明确指定顺序：

{
  "email": "signer1@example.com",
  "name": "签署人1",
  "roleName": "角色1",
  "routingOrder": "1", // 第一个签署
  "tabs": {...}
},
{
  "email": "signer2@example.com",
  "name": "签署人2",
  "roleName": "角色2",
  "routingOrder": "2", // 第二个签署
  "tabs": {...}
}

4. 动态添加姓名、签名、日期标签 #

• 姓名标签：用textTabs，可直接赋值数据库姓名（设locked: true防止修改）或留空让签署人填写
• 签名标签：用signHereTabs，通过坐标或锚点定位
• 日期标签：用dateSignedTabs，签署完成后自动填充当前日期，无需手动赋值

示例片段：

"tabs": {
  "textTabs": [
    {
      "documentId": "1",
      "pageNumber": "1",
      "xPosition": "80",
      "yPosition": "120",
      "tabLabel": "姓名",
      "value": "testname",
      "locked": "true"
    }
  ],
  "signHereTabs": [
    {
      "documentId": "1",
      "pageNumber": "1",
      "xPosition": "80",
      "yPosition": "180",
      "tabLabel": "签名"
    }
  ],
  "dateSignedTabs": [
    {
      "documentId": "1",
      "pageNumber": "1",
      "xPosition": "200",
      "yPosition": "180",
      "tabLabel": "日期"
    }
  ]
}

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