使用DocuSign REST API获取/设置模板字段 [英] Using DocuSign REST APIs to Get/Set Template Fields

问题描述

我已经在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中实际引用这些字段。现在的问题仍然是为什么只为单个收件人角色返回它们。以下是角色在信封上的截图（电子邮件地址已被编辑）：

即使该角色标记为需要签名，也不会返回那个家伙的选项卡。即使角色只是为了被复制，也将返回其他人。因此，现在看来问题似乎更多地与角色定义有关。或者，我必须再次回顾所有这一切，因为必须为所有收件人设置需要预填充的这些字段，并且这些字段与角色无关。

解决方案

DocuSign使用（至少）3种不同方式的自定义字段一词：

• 信封自定义字段，您可以指定在信封级别关联的元数据。收件人看不到此数据；只是多余的元数据，您可以将其与信封关联，然后再通过API查询。详情请参阅此处。




• 文档自定义字段使您可以指定在文档级别关联的元数据。收件人无法以任何方式看到此数据；它只是多余的元数据，您可以将其与特定文档相关联，然后再通过API查询。详情请参阅此处。




• 自定义字段（也称为自定义标签），您可以创建（并保存）自己的自定义标签以便在文档中使用-请参见此处和此处了解更多信息。

根据您在问题中提供的信息，我想您正在使用自定义字段一词来指代您的标签放置在模板中的整个文档中，其中一些您希望在创建信封时通过API动态填充数据，而另一些则希望收件人在签名期间填充数据。那是对的吗？

如果这是您的意思，则可以通过执行列出信封标签来获得特定收件人拥有的标签（字段）列表。请求，如此处所述。

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

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

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

I've created a test template within the DocuSign sandbox in preparation for some automation with another system. I'm trying to populate these custom fields as there will be dynamically entered data that will need to be included.

So far, I've had no trouble with authentication, or creating an "envelope" built off of the template, or assigning the roles. I can get the IDs of the templates, envelopes, documents no problem. However, none of my attempts to retrieve a list of the custom fields or populate them through the REST APIs have been successful.

I've made attempts to pull fields from the template, and from the envelope after applying the template. I've even manually set the values through the UI, but still got nothing. And the requests aren't failing. They're successful. There's just either empty respond data structures, or no update performed.

For example, when I attempt to retrieve the custom fields, this is what I get:

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

This is despite having created custom fields through the UI and applying them to template and such. I also tried getting the document fields instead, but received essentially the same response:

{
  "documentFields": []
}

I can't help but think I'm missing something here and don't know what. I pull the base URL from the authentication response, and I've made calls to the following API URLs:

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

-- EDIT --

Ok, so following on suggestions from an answer below, I found that the fields are all actually "tabs", despite how they were actually referenced in the UI during creation of the template. Now the question remains why they are only returned for a single recipient role. Here's a screenshot of how the roles are on the envelope (email addresses are edited over):

The tabs are not returned for "That Guy", even though that role is marked "Needs to Sign". They are returned for "Other Guy", even though that role is just meant to get copied. So, maybe it now looks like the problem has more to do with role definition than anything else. Or I have to go back review all this again because these fields in need of pre-population have to be set for all recipients and are not role-dependent. Everyone is meant to see the same thing.

解决方案

DocuSign uses the term "custom fields" in (at least) 3 different ways:

• Envelope Custom Fields let you specify metadata that gets associated at the Envelope level. This data isn't visible to recipients; it's just extra metadata that you can associate with an Envelope and query later (via API). See here for more info.

• Document Custom Fields let you specify metadata that gets associated at the Document level. This data isn't visible to recipients in any way; it's just extra metadata that you can associate with a specific Document and query later (via API). See here for more info.

• Custom Fields (aka "custom tabs") let you create (and save) your own customized tabs for use in your documents -- see here and here for more info.

Based on the information you've provided in you're question, I'd guess that you're using the term "custom fields" to refer to the tabs you placed throughout the document(s) in the template, some of which you want to dynamically populate with data via API when the envelope gets created, and others that recipients will populate with data during signing. Is that correct?

If this is what you mean, you can get a list of tabs (fields) that a specific recipient owns by executing a List Envelope Tabs request, as described here.

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

To retrieve tabs for a template (rather than an envelope), use this same URI, but specify the Template ID value in place of {envelopeId}. Also, note that the value that you specify for {recipientId} should identify the recipient who "owns" the tabs in the template/envelope. (Each tab in a template/envelope is "owned" by a specific recipient.)

If I've misunderstood your issue (or what you mean by "custom fields"), please comment on this answer and I'll attempt to clarify further.

这篇关于使用DocuSign REST API获取/设置模板字段的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！