如何用prefillTabs和titleTabs预填充已有DocuSign模板？求示例

问题 #

在使用DocuSign模板自动填充时遇到两个核心问题：

• textTabs可正常填充文本字段，但titleTabs无法填充Title类型的模板字段
• 不清楚prefillTabs的正确放置位置，当前放在收件人tabs下无法生效

使用技术栈：Elixir + 非官方DocuSign库，数据结构与官方API一致，当前实现代码如下：

signer = %TemplateRole{
      email: to.email,
      name: to.name,
      roleName: "Client",
      tabs: %EnvelopeRecipientTabs{
        titleTabs: [
          # TODO: Title tabs are not prefilling the Title type field
          %DocuSign.Model.Title{
            value: "My Title",
            tabLabel: "Title c1e5eba4-fcea-4ebd-a7fd-55339689b5c7"
          }
        ],
        textTabs: [
          %DocuSign.Model.Text{
            value: "My Text",
            tabLabel: "Text 78971077-4685-4e5f-b1d6-c8371a5d5168"
          }
        ],
        prefillTabs: %PrefillTabs{
          textTabs: [
            %DocuSign.Model.Text{
              value: Date.utc_today() |> to_string(),
              tabLabel: "Effective Date dc501978-6c07-425d-84ba-b1d5eba1814c"
            }
          ]
        }
      }
    }

查阅官方文档未找到对应示例：模板填充指南未覆盖Title字段，预填充教程未基于已有模板场景。

解决方案 #

1. 修复Title字段填充失效问题 #

Title类型字段确实需要通过titleTabs设置，但需满足两个关键条件：

• TabLabel完全匹配：核对模板中Title字段的API标签，确保与代码中tabLabel的字符串完全一致（包括空格、UUID后缀），可在DocuSign模板编辑页的字段属性中查看该值
• 可选：指定RecipientId：若模板中该Title字段绑定了特定收件人角色，需额外添加recipientId字段（通常为"1"对应第一个收件人）

调整后的titleTabs代码片段：

titleTabs: [
  %DocuSign.Model.Title{
    value: "My Title",
    tabLabel: "Title c1e5eba4-fcea-4ebd-a7fd-55339689b5c7",
    recipientId: "1" # 仅当模板字段绑定特定收件人时需要
  }
]

2. PrefillTabs的正确层级 #

prefillTabs是信封层级的属性，不属于单个收件人的tabs子节点。预填充字段全局生效，不绑定到特定收件人角色，需直接放在EnvelopeDefinition中。

调整后的完整信封定义示例：

# 先定义收件人角色
signer = %TemplateRole{
  email: to.email,
  name: to.name,
  roleName: "Client",
  tabs: %EnvelopeRecipientTabs{
    titleTabs: [
      %DocuSign.Model.Title{
        value: "My Title",
        tabLabel: "Title c1e5eba4-fcea-4ebd-a7fd-55339689b5c7"
      }
    ],
    textTabs: [
      %DocuSign.Model.Text{
        value: "My Text",
        tabLabel: "Text 78971077-4685-4e5f-b1d6-c8371a5d5168"
      }
    ]
  }
}

# 信封定义中加入prefillTabs
envelope_definition = %DocuSign.Model.EnvelopeDefinition{
  templateId: "YOUR_TEMPLATE_ID", # 替换为你的模板ID
  status: "sent",
  templateRoles: [signer],
  prefillTabs: %DocuSign.Model.PrefillTabs{
    textTabs: [
      %DocuSign.Model.Text{
        value: Date.utc_today() |> to_string(),
        tabLabel: "Effective Date dc501978-6c07-425d-84ba-b1d5eba1814c"
      }
    ]
  }
}

额外注意：模板中的预填充字段需设置为"预填充"类型，而非绑定到某收件人角色，否则无法通过该方式填充。

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