使用 REST API 设置文档值

Question

我正在尝试通过 Docusign Esignature REST API 填写文档字段，但遇到了一些问题。我从具有 PO # 字段的模板创建了一个信封：

我可以通过对 /restapi/v2.1/accounts/#######/envelopes/466077c7-#######/documents/1/tabs 进行 GET 调用来查看此字段：

validationPattern            : 
validationMessage            : 
shared                       : false
requireInitialOnSharedChange : false
requireAll                   : false
value                        : 
required                     : true
locked                       : false
concealValueOnDocument       : false
disableAutoSize              : false
maxLength                    : 10
tabLabel                     : PO #
font                         : lucidaconsole
fontColor                    : black
fontSize                     : size9
localePolicy                 : 
documentId                   : 1
recipientId                  : 0287bf0a-2951-4902-b63d-2f438d70a64a
pageNumber                   : 1
xPosition                    : 383
yPosition                    : 61
width                        : 166
height                       : 20
tabId                        : fd51de92-1ccb-4343-81bf-7fd2dbb9ae57
templateRequired             : false
tabType                      : number

如果我在 GUI 的字段中手动键入一个值并退出而不叹气，它会反映在同一调用中的值字段中。但是，当我尝试通过 API 通过 PUT 调用 /restapi/v2.1/accounts/######/envelopes/466077c7-######/documents/1/tabs 来更新字段值时有效载荷设置为：

{
            "tabs": {
                "numberTabs": [{
                    "tabLabel": "PO #",
                    "value": "123123123123"
                }]
            }
}

失败并显示我不明白的相当模糊的错误消息：

{"errorCode":"UNSPECIFIED_ERROR","message":"Value cannot be null.\r\nParameter name: source"}

查看 API 参考，没有名为“source”的字段，所以我不知道如何进行此操作。我尝试在我的 JSON 中以几种不同的方式引用该字段 - 通过标签、guid 等，但似乎没有任何效果。我的语法有问题吗？

Answer 1

在元素的 DocuSign 电子签名层次结构中，信封包含文档和收件人，并且选项卡必须与两者相关联。因此，有两个不同的端点可用于更新选项卡的值，但它们的工作方式不同。您试图使用Envelopes::UpdateDocumentTabs 方法，而您应该使用Envelope::UpdateTabs 方法。前一种方法主要用于较新的功能，例如document markup，即使在锁定时（意味着当前打开以进行签名），也可以修改文档，而后一种方法是集成更新信封选项卡内容的正确方法。

Answer 2

DocuSign 的电子签名 API 使用 PUT，而不是 PATCH。

所以问题在于，当您使用PUT 方法时，您正在更新给定文档或收件人的所有信封标签。如果现有选项卡不在 PUT 调用的请求对象中，则您将它们设置为 null。这就是导致错误的原因。

所以我使用的解决方案是首先list 信封收件人的所有选项卡，然后根据需要更新数据结构，然后update (put) 更新的选项卡结构。

在这个答案中，我使用的是 EnvelopeRecipientTabs 资源。您的示例使用 EnvelopeDocumentTabs 资源。这应该可以，但请注意来自get 的响应数据结构不与put 的请求数据结构相同。因此，您需要根据需要调整数据结构。

使用 EnvelopeRecipientTabs 资源，来自get 的响应数据结构与put 的请求数据结构相同，因此我认为需要更少的代码。此外，在 DocuSign 对象模型中，选项卡属于收件人。它们出现在文档上，但属于收件人。