使用 DocuSign REST API 获取/设置模板字段

Question

我在 DocuSign 沙箱中创建了一个测试模板，为与另一个系统进行一些自动化做准备。我正在尝试填充这些自定义字段，因为需要包含动态输入的数据。

到目前为止，我在身份验证、创建基于模板的“信封”或分配角色方面没有遇到任何问题。我可以毫无问题地获取模板、信封、文档的 ID。但是，我尝试检索自定义字段列表或通过 REST API 填充它们都没有成功。

我尝试从模板中提取字段，并在应用模板后从信封中提取字段。我什至通过用户界面手动设置了值，但仍然一无所获。而且请求并没有失败。他们很成功。要么只有空的响应数据结构，要么没有执行更新。

例如，当我尝试检索自定义字段时，我得到的是：

{
  "textCustomFields": [],
  "listCustomFields": []
}

尽管已经通过 UI 创建了自定义字段并将其应用到模板等，但仍然如此。我也尝试获取文档字段，但收到的响应基本相同：

{
  "documentFields": []
}

我忍不住想我在这里错过了一些东西，但不知道是什么。我从身份验证响应中提取基本 URL，并调用了以下 API URL：

• /信封/{1}/custom_fields
• /信封/{1}/文档/{2}/字段
• /envelopes/{1}/recipients/{2}/tabs
• /templates/{1}/custom_fields
• /templates/{1}/documents/{2}/fields

- 编辑 -

好的，根据下面答案的建议，我发现这些字段实际上都是“选项卡”，尽管在创建模板期间如何在 UI 中实际引用它们。现在的问题仍然是为什么它们仅针对单个收件人角色返回。以下是信封上角色的屏幕截图（电子邮件地址已编辑）：

即使该角色被标记为“需要签名”，也不会返回“That Guy”的选项卡。他们因“其他人”而回归，尽管这个角色只是为了被复制。所以，也许现在看来问题更多地与角色定义有关，而不是其他任何事情。或者我必须再次回顾所有这些，因为必须为所有收件人设置这些需要预先填充的字段，并且不依赖于角色。每个人都应该看到同样的事情。

Answer 1

DocuSign 以（至少）3 种不同的方式使用术语“自定义字段”：

• 信封自定义字段允许您指定在信封级别关联的元数据。此数据对收件人不可见；它只是额外的元数据，您可以将其与信封关联并稍后查询（通过 API）。请参阅此处了解更多信息。

• 文档自定义字段允许您指定在文档级别关联的元数据。这些数据对接收者来说是不可见的；它只是额外的元数据，您可以将其与特定文档关联并稍后查询（通过 API）。请参阅此处了解更多信息。

• 自定义字段（又名“自定义选项卡”）可让您创建（并保存）自己的自定义选项卡以在文档中使用 - 请参阅此处和此处了解更多信息。

根据您在问题中提供的信息，我猜您使用术语“自定义字段”来指代选项卡，其中一些选项卡是您在希望在创建信封时通过 API 动态填充数据，以及收件人在签名期间填充数据的其他内容。那是对的吗？

如果这就是您的意思，您可以通过执行“列出信封选项卡”请求来获取特定收件人拥有的选项卡（字段）列表，如此处所述。

GET /v2/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs

要检索模板（而不是信封）的选项卡，请使用相同的 URI，但指定模板 ID值来代替{envelopeId}。另请注意，您为{recipientId}指定的值应标识“拥有”模板/信封中的选项卡的收件人。（模板/信封中的每个选项卡均由特定收件人“拥有”。）

如果我误解了您的问题（或您所说的“自定义字段”的含义），请对此答案发表评论，我将尝试进一步澄清。