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

Question

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

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

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

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

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

尽管已通过 UI 创建自定义字段并将它们应用于模板等。我也尝试获取文档字段，但收到的响应基本相同:

{
  "documentFields": []
}

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

• /envelopes/{1}/custom_fields
• /envelopes/{1}/documents/{2}/fields
• /envelopes/{1}/recipients/{2}/tabs
• /templates/{1}/custom_fields
• /templates/{1}/documents/{2}/fields

-- 编辑 --

好吧，按照下面答案的建议，我发现这些字段实际上都是“选项卡”，尽管在创建模板期间它们实际上是如何在 UI 中引用的。现在的问题仍然是为什么只为单个收件人角色返回它们。这是角色在信封上的截图(电子邮件地址被编辑):

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

Answer 1

DocuSign 在(至少)3 种不同的方式中使用术语“自定义字段”:

• 信封自定义字段让您可以指定在信封级别关联的元数据。此数据对收件人不可见；它只是额外的元数据，您可以将其与信封相关联并稍后查询(通过 API)。有关详细信息，请参阅 here。

• 文档自定义字段让您可以指定在文档级别关联的元数据。这些数据对收件人来说是不可见的；它只是额外的元数据，您可以将其与特定文档相关联并稍后查询(通过 API)。有关详细信息，请参阅 here。

• 自定义字段(又名“自定义选项卡”)让您创建(并保存)您自己的自定义选项卡以用于您的文档 -- 请参阅 here 和here 了解更多信息。

根据您在问题中提供的信息，我猜您正在使用术语“自定义字段”来指代您在整个文档中放置的选项卡( s) 在模板中，其中一些您希望在创建信封时通过 API 动态填充数据，而其他一些则收件人将在签名期间填充数据。那是对的吗？

如果这是您的意思，您可以通过执行 List Envelope Tabs 请求获取特定收件人拥有的选项卡(字段)列表，如 here 所述。

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

要检索模板(而不是信封)的标签，请使用相同的 URI，但在适当的位置指定模板 ID 值{envelopeId}。另请注意，您为 {recipientId} 指定的值应标识“拥有”模板/信封中的选项卡的收件人。 (模板/信封中的每个标签都由特定收件人“拥有”。)

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