如何获取DocuSign信封中手动应用模板的页面范围？

核心问题 #

使用模板匹配（template matching）发送的信封，可通过API获取包含documentStartPage和documentEndPage的模板页面范围数据，进而拆分合并PDF；但手动应用模板创建的信封，创建时用户指定过模板起始页，却无法通过现有API查询到该页面范围信息，导致无法按模板拆分PDF。

可行实现方案 #

1. 信封创建阶段注入自定义元数据 #

在通过API或UI创建信封、手动应用模板时，强制将模板的templateId、起始页、结束页（可通过模板定义的页面数推导，除非用户手动调整字段）存入信封的**自定义字段（Custom Fields）**中：

• 若用API创建：调用信封创建接口时，在customFields节点添加键值对，示例如下：

"customFields": {
  "textCustomFields": [
    {
      "name": "template_<templateId>_startPage",
      "value": "1",
      "show": "false"
    },
    {
      "name": "template_<templateId>_endPage",
      "value": "3",
      "show": "false"
    }
  ]
}

• 若用UI创建：配置DocuSign模板或信封模板时，添加隐藏的文本自定义字段，让用户手动应用模板时填写或自动带入起始页，再根据模板页面数计算结束页。

后续处理已完成信封时，先调用API获取信封的自定义字段，提取各模板的页面范围，再拆分PDF。

2. 解析信封文档的Tab关联信息 #

虽然直接通过tabId关联模板的信息有限，但可通过以下方式推导页面范围：

• 调用GET /envelopes/{envelopeId}/tabs接口获取所有签名字段，每个Tab的templateLocked、templateRequired字段可判断是否来自模板；
• 提取来自同一模板的Tab的pageNumber值，最小的pageNumber即为该模板的起始页，再结合模板本身的页面数（调用GET /templates/{templateId}获取模板总页数）推导结束页；
• 例外情况：若用户手动移动了跨页模板的字段，需结合字段分布的页面范围做修正，比如取所有该模板字段所在页面的最小和最大值作为起始/结束页。

3. 测试扩展API端点 #

尝试调用GET /envelopes/{envelopeId}/documents/{documentId}/template_applications（部分环境支持），该端点可能返回手动应用模板时的页面映射信息；若官方文档未提及，可通过API Explorer测试该端点的可用性。

注意事项 #

• 若依赖模板页面数推导结束页，需确保模板本身的页面数未被用户在信封创建时修改（比如删除/添加页面），否则需结合实际PDF的页面数做调整；
• 自定义字段需设置为隐藏（show: false），避免影响签署流程。

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