如何通过Docusign REST API为动态生成的PDF合同添加自定义复选框？

没问题，这个需求完全可以通过DocuSign的REST API实现，核心就是动态给外部生成的PDF添加复选框字段，效果和你手动创建模板时的功能一模一样。我给你拆解下具体步骤和细节：

核心思路 #

DocuSign允许你在创建信封时，直接给上传的外部PDF文档添加各类表单字段（包括复选框），不需要预先在PDF里嵌入这些字段。你只需要在API请求中定义好复选框的位置、属性，客户签署时就能看到并操作这些复选框。

具体实现步骤 #

1. 准备好你的自定义PDF文档 #

确保你的代码生成的PDF是标准格式（无加密、可正常解析），后续可以通过两种方式传给DocuSign：

• 直接把PDF的字节流包含在信封创建请求中
• 先上传到DocuSign的文件存储，再引用其URL

2. 在信封创建请求中动态定义复选框字段 #

在调用Envelopes: create接口时，给目标收件人的tabs参数添加checkboxTabs数组，每个数组元素对应一个动态复选框。下面是一个JSON请求体的关键片段示例：

"recipients": {
  "signers": [
    {
      "email": "customer@yourdomain.com",
      "name": "终端客户姓名",
      "recipientId": "1",
      "tabs": {
        "checkboxTabs": [
          {
            "documentId": "1", // 对应你上传的PDF在信封中的ID，通常第一个文档为"1"
            "pageNumber": "1", // 复选框所在的页码
            "xPosition": "120", // 页面上的X坐标（像素，从左到右）
            "yPosition": "300", // 页面上的Y坐标（像素，从上到下）
            "tabLabel": "AgreeToTerms", // 字段唯一标识，用于后续查询签署状态
            "required": "false", // 是否必填：false=客户可填可不填，true=必须勾选
            "selected": "false", // 默认是否勾选
            "height": "22",
            "width": "22"
          },
          {
            // 第二个动态复选框示例
            "documentId": "1",
            "pageNumber": "1",
            "xPosition": "120",
            "yPosition": "340",
            "tabLabel": "OptInNewsletter",
            "required": "false",
            "selected": "false"
          }
        ]
      }
    }
  ]
}

3. 关键细节注意事项 #

• 坐标定位：如果不确定PDF的精确坐标，可以先在DocuSign Web界面手动给该PDF添加一个复选框，然后调用Envelopes: getTabs接口获取字段的参数，以此作为动态生成坐标的参考；如果你的PDF布局是固定的，也可以直接在代码里计算坐标。
• 动态生成字段：如果复选框的数量、内容是根据业务逻辑变化的（比如从数据库读取选项），只需要在代码里循环生成checkboxTabs的对象数组即可，完全适配动态场景。
• 字段状态跟踪：签署完成后，你可以通过Envelopes: getTabs接口获取每个复选框的selected值，知道客户是否勾选了对应的选项。

完整流程回顾 #

1. 你的自定义代码生成目标PDF
2. 调用DocuSign Envelopes: create接口，传入PDF文档信息+动态生成的复选框字段配置+收件人信息
3. 客户收到签署邮件，打开后即可看到所有动态添加的复选框，可选择勾选或不勾选，完成签署
4. 你通过API查询签署状态和复选框的选择情况

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