Docusign：使用REST API和预填充标签通过模板创建信封 [英] Docusign: creating envelopes through templates with the REST API and prefilling tags
问题描述
我正在整合Docusign，以便收件人可以看到他们的信封嵌入我的网站。我首先使用api创建信封，然后尝试使用动态数据预填充数据字段。
I'm integrating Docusign so that recipients can see their envelopes embedded on my site. I first create the envelope with the api, and I'm attempting to prefill Data Fields using dynamic data.
据我所知，我的json没什么问题我用来创建信封的那个StackOverflow上针对该问题的其他解决方案均无济于事。我的json看起来像这样（我发送给 https://demo.docusign.net / restapi / v2 / accounts / 360734 /信封）：
As far as I can tell, there's nothing wrong with my json that I'm using to create the envelopes. None of the other solutions on StackOverflow to this issue have helped. My json looks like this (which I send to https://demo.docusign.net/restapi/v2/accounts/360734/envelopes):
{
"status": "sent",
"emailBlurb": "Please sign the document.",
"emailSubject": "Please sign your agreement",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"clientUserId": "EMAIL",
"name": "NAME",
"email": "EMAIL",
"roleName": "Signer1",
"tabs": {
"textTabs": [
{
"tabLabel": "address",
"value": "ADDRESS "
},
{
"tabLabel": "multi_address",
"value": "ADDRESSES"
}
]
}
},
{
"name": "ANOTHER NAME",
"email": "ANOTHER EMAIL",
"roleName": "Random1"
}
]
}
我得到以下响应：
{
"envelopeId": "ENVELOPE_ID",
"uri": "/envelopes/ENVELOPE_ID",
"statusDateTime": "2013-10-25T01:20:55.6750772Z",
"status": "sent"
}
然后我将链接发布到 https://demo.docusign.net/restapi/v2/accounts/360734/envelopes/ENVELOPE_ID/views/recipient
{
"authenticationMethod": "email",
"clientUserId": "EMAIL",
"email": "EMAIL",
"returnUrl": "MYURL",
"userName": "NAME"
}
我得到以下答复：
{
"url": "https://demo.docusign.net/Member/StartInSession.aspx?t=REDACTED"
}
这遵循此处显示的示例： https://github.com/Ergin008/DocuSign-REST-API-Webinar-April2013/blob/master/example2.json
This follows the example seen here: https://github.com/Ergin008/DocuSign-REST-API-Webinar-April2013/blob/master/example2.json
以这种方式创建信封后，标签似乎没有预填充。当我查看嵌入在我网站上的信封时，什么也没填。我确定tabLabels是正确的。否则一切似乎都正常。我缺少某种设置吗？
After creating the envelope this way, it appears that the tags do not prefill. When I view the envelope embedded on my site, nothing is filled. I'm certain the tabLabels are correct. Everything otherwise seems to be working okay. Is there some kind of setting I'm missing?
UPDATE
看起来可能是个错误！我只更改角色名称即可使用！
UPDATE Looks like it could be a bug! All I change is the role name and it works!
{
"status": "sent",
"emailBlurb": "Please sign the document.",
"emailSubject": "Please sign your agreement",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"clientUserId": "EMAIL",
"name": "NAME",
"email": "EMAIL",
"roleName": "Signer1",
"tabs": {
"textTabs": [
{
"tabLabel": "address",
"value": "ADDRESS "
},
{
"tabLabel": "multi_address",
"value": "ADDRESSES"
}
]
}
},
{
"name": "ANOTHER NAME",
"email": "ANOTHER EMAIL",
"roleName": "Signer2"
}
]
}
然后填充！如果我用Signer以外的任何其他字符开头角色名称，那似乎不起作用。
And it populated! It seems if I start the role name with anything other than Signer it doesn't work. Weird!
是的，在这种情况下，我将Docusign上的角色名称从Random1更改为Signer2。例如，Signer3也起作用。
And yes, I'm changing the role name on Docusign from Random1 to Signer2, in this case. For example, Signer3 also worked.
推荐答案
您的问题是您将JSON提交到获取收件人视图资源：
Your question says your submitting that JSON to the "Get Recipient View" resource:
https://demo.docusign.net/restapi/v2/accounts/ACCOUNT_ID/envelopes/ENVELOPE_ID/views/recipient)
...但是该JSON类似于您在创建信封请求中使用的JSON，而不是在获取收件人视图请求。因此，让我首先说明促进嵌入式/强制签名的过程（即在您的站点内显示收件人的信封）。这样做分为两个步骤：
...but that JSON looks like what you use in the "Create Envelope" request, not the "Get Recipient View" request. So, let me start by clarifying the process of facilitating Embedded/captive signing (i.e., presenting the recipient's envelope within your site). Doing so is a two-step process:
第1步：创建信封（请求中包含为每个收件人预填充字段的数据，
STEP 1: Create the envelope (request includes data to pre-populate fields for each recipient, if needed).
POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes
请参阅从REST API指南的p27开始的从模板创建信封部分（< a href = http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf rel = noreferrer> http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf ）以获取有关请求和响应的详细信息。
See "Creating an Envelope From a Template" section that starts on p27 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for detailed info about request and response.
第2步：检索可用于启动收件人信封的URL（签名会话）。
STEP 2: Retrieve the URL that can be used to launch the recipient's envelope (signing session).
POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes/{envelopeId}/views/recipient
{
"authenticationMethod":"Email",
"clientUserId":"CLIENT_USERID_SPECIFIED_IN_REQUEST",
"email":"RECIPIENT_EMAIL",
"returnUrl":"URL_TO_REDIRECT_TO_WHEN_SIGNING_COMPLETE",
"userName":"RECIPIENT_NAME"
}
响应将包含可用于启动收件人信封的URL：
The response will contain the URL that can be used to launch the Recipient's Envelope:
{
"url":"URL_THAT_WILL_LAUNCH_ENVELOPE"
}
请参阅后收件人视图部分从REST API指南的p160（ http://www.docusign.com /sites/default/files/REST_API_Guide_v2.pdf ）以获取有关请求和响应的更多详细信息。
See the "Post Recipient View" section that starts on p160 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for more detailed info about request and response.
现在，假设您正确执行了所有操作（步骤1和步骤2）-让我们得到b解决您要报告的问题：难以为收件人预填充字段。问题中包含有关从模板创建信封 JSON的一些注释：
Now, assuming you're doing all this correctly (step 1 and step 2) -- let's get back to the issue you're reporting: difficulty pre-populating fields for the recipient. A few comments about the "Create Envelope from Template" JSON that you included in your question:
- 您不需要 accountId 在请求中。
- 您无需在选项卡的请求中包含 documentId 和 pageNumber 。
- 如果您希望接收者在您的网站内进行嵌入/强制签名，则必须在请求中包括 clientUserId 。 $ b
- You don't need accountId in request.
- You don't need to include documentId and pageNumber in the request for the tab.
- You DO need to include clientUserId for the recipient in the request, if you want the recipient to sign embedded/captive within your site.
因此，这是一个从模板创建/发送信封示例请求（上面的第1步），它预先填充了名为 FIELD_1在信封中出现的任何位置均带有值 VALUE_A：
So, here's a "Create/Send Envelope From Template" example request (step 1 above) that pre-populates the tab named "FIELD_1" with the value "VALUE_A" anywhere that it appears in the envelope:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"status" : "sent",
"emailBlurb" : "please sign",
"emailSubject" : "Please sign your document",
"templateId" : "TEMPLATE_ID",
"templateRoles" : [{
"name" : "John Doe",
"email" : "JohnsEmail@outlook.com",
"roleName" : "Signer1Role",
"clientUserId" : "123",
"tabs" :
{"textTabs":[{
"tabLabel":"\\*FIELD_1",
"value":"VALUE_A"}
]}
}]
}
然后，您将获取响应中返回的信封ID并调用获取收件人视图资源（上述第2步）来获取URL启动签名会话：
Then, you'd take the Envelope Id that's returned in the response and call the "Get Recipient View" resource (step 2 above) to get the URL to launch the signing session:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient
{
"authenticationMethod": "Email",
"clientUserId": "123",
"userName": "John Doe",
"email": "JohnsEmail@outlook.com",
"returnUrl": "http://www.google.com"
}
最后，最后一条评论（但重要的一条）：如果您只是想在文档中注入收件人的全名，请在创建模板和DocuSign时使用 全名标签会自动在该标签出现的任何位置插入收件人的姓名，以代替该标签（而不是您使用文本标签，而必须通过API请求进行填充）。这是DocuSign UI标记视图中的全名标记：
Finally, one last comment (but an important one): if you're just wanting to inject the recipient's "full name" in the document -- use the "Full Name" tab when creating the Template and DocuSign will automatically inject the recipient's name in place of that tag, anywhere that it appears (instead of you using a Text Tab and having to populate it via the API request). Here's the Full Name tag in the DocuSign UI tagger view:
另一个创建信封示例（带有数据字段属性的屏幕截图）：
如果我提交此请求：
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign this",
"emailBlurb": "Please sign...thanks!",
"templateId": "TEMPLATE_ID",
"envelopeIdStamping": "false",
"templateRoles": [
{
"roleName": "Signer1",
"name": "John Doe",
"email": "JohnsEmail@outlook.com",
"recipientId": "1",
"tabs":{
"textTabs":[
{
"tabLabel":"\\*address",
"value":"123 Main Street"
},
],
}
}
],
"status": "sent"
}
数据字段属性（通过DocuSign UI编辑模板时）如下所示：
And the Data Field properties (when Editing the Template via the DocuSign UI) look like this:
然后，结果是带有Label = address 的字段当签名者查看其信封时，分配给收件人角色 Signer1 的>将预先填充值 123 Main Street。如果这不适合您，我建议您：
Then the result is that field(s) with Label = address that are assigned to Recipient Role Signer1 will be prepopulated with the value "123 Main Street" when the signer views their envelope. If this isn't working for you, I suggest that you:
- 验证在其中的 roleName 的值API请求完全与我在上一个屏幕截图中突出显示的收件人值匹配（在我的示例中为 Signer1）。
- 验证< API请求中的strong> tabLabel 完全与我在上一个屏幕截图中突出显示的Label值（在我的示例中为地址。）
- Verify that the value of roleName in the API request exactly matches the Recipient value I've highlighted in the prior screenshot (in my example, "Signer1").
- Verify that the value of tabLabel in the API request exactly matches the Label value I've highlighted in the prior screenshot (in my example, "address).
注意 ：值是 区分大小写 ，因此确保您请求中的值与数据字段标记属性中的值 精确 匹配（包括大写/小写）。
Note: Values are case-sensitive, so be sure values in your request are an exact match (including upper-case/lower-case) with the values in the Data Field Tag Properties.
这篇关于Docusign：使用REST API和预填充标签通过模板创建信封的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
