Docusign API服务器模板本地文档和选项卡 [英] Docusign API server templates local docs and tabs
问题描述
我正在研究DocuSign集成。我具有基本功能，但似乎无法弄清楚如何将本地文档（PDF）与服务器模板合并，以使服务器模板上配置的标签被使用或覆盖在传递的文档上。
I'm working on a DocuSign integration. I have the basics functional but can't seem to figure out how to merge a local document (PDF) with a server template such that tabs configured on the server template get used or overlaid on the passed document.
我的模板是在服务器上定义的，我可以直接从Web用户界面使用它，而不会出现问题（这是W4表单）。模板具有三个标签（SSN，在此处签名和日期），如下所示。使用API资源管理器通过其ID访问该模板会产生以下json
My template is defined on the server and I can use it directly from the web UI without issue (it's a W4 form). The template has three tabs (SSN, Sign here, and date) as you can see below. Accessing this template via it's ID using the API Explorer yields the following json
{
"envelopeTemplateDefinition": {
"templateId": "_redacted_",
"name": "W4 3/13/2017",
"shared": "true",
"password": "",
"description": "",
"lastModified": "2017-06-05T18:45:28.4470000Z",
"lastModifiedBy": {
"userName": "Andrew",
"userId": "_redacted_",
"email": "my_email_address",
"uri": "/users/_redacted_
},
"pageCount": 2,
"uri": "/templates/_redacted_",
"folderName": "Templates",
"folderId": "_redacted_",
"folderUri": "/folders/_redacted_",
"owner": {
"userName": "Andrew",
"userId": "_redacted_",
"email": "my_email_address"
}
},
"documents": [
{
"documentId": "46677269",
"uri": "/envelopes/_redacted_/documents/46677269",
"name": "W4.pdf",
"order": "1",
"pages": "2",
"display": "inline",
"includeInDownload": "true",
"signerMustAcknowledge": "no_interaction",
"templateLocked": "false",
"templateRequired": "false",
"documentGroup": "content"
}
],
"emailSubject": "Please DocuSign: W4.pdf",
"emailBlurb": "",
"signingLocation": "online",
"autoNavigation": "true",
"envelopeIdStamping": "true",
"authoritativeCopy": "false",
"notification": {
"reminders": {
"reminderEnabled": "false",
"reminderDelay": "0",
"reminderFrequency": "0"
},
"expirations": {
"expireEnabled": "true",
"expireAfter": "120",
"expireWarn": "0"
}
},
"enforceSignerVisibility": "false",
"enableWetSign": "true",
"allowMarkup": "false",
"allowReassign": "true",
"recipients": {
"signers": [
{
"defaultRecipient": "false",
"tabs": {
"signHereTabs": [
{
"stampType": "signature",
"name": "SignHere",
"tabLabel": "Signature _redacted_",
"scaleValue": 1.0,
"optional": "false",
"documentId": "46677269",
"recipientId": "94043042",
"pageNumber": "1",
"xPosition": "193",
"yPosition": "682",
"tabId": "_redacted_",
"templateLocked": "false",
"templateRequired": "false"
}
],
"dateSignedTabs": [
{
"name": "DateSigned",
"value": "",
"tabLabel": "Date Signed _redacted_",
"font": "lucidaconsole",
"fontColor": "black",
"fontSize": "size9",
"documentId": "46677269",
"recipientId": "94043042",
"pageNumber": "1",
"xPosition": "480",
"yPosition": "713",
"tabId": "_redacted_",
"templateLocked": "false",
"templateRequired": "false"
}
],
"ssnTabs": [
{
"validationPattern": "",
"validationMessage": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"requireAll": "false",
"value": "",
"width": 144,
"required": "true",
"locked": "false",
"concealValueOnDocument": "true",
"disableAutoSize": "false",
"maxLength": 4000,
"tabLabel": "Text _redacted_",
"font": "lucidaconsole",
"fontColor": "black",
"fontSize": "size9",
"documentId": "46677269",
"recipientId": "94043042",
"pageNumber": "1",
"xPosition": "442",
"yPosition": "563",
"tabId": "_redacted_",
"templateLocked": "false",
"templateRequired": "false"
}
]
},
"signInEachLocation": "false",
"name": "",
"email": "",
"recipientId": "94043042",
"accessCode": "",
"requireIdLookup": "false",
"routingOrder": "1",
"note": "",
"roleName": "New Employee",
"deliveryMethod": "email",
"templateLocked": "false",
"templateRequired": "false",
"inheritEmailNotificationConfiguration": "false"
}
],
"agents": [ ],
"editors": [ ],
"intermediaries": [ ],
"carbonCopies": [ ],
"certifiedDeliveries": [ ],
"inPersonSigners": [ ],
"recipientCount": "1"
}
}
我要做的是将此模板应用于已经部分填写的PDF，以便在签署者得到签名时使用服务器模板中定义的选项卡进行。
What I want to do is apply this template to a PDF that's already partially filled out such that when the signer get's it the tabs defined in the server template are used for the sining.
就目前而言，什么都没有。我只是将下面部分填充的PDF作为base64数据传入，而没有服务器模板选项卡可填充或签名。这是API调用的我的json（在PHP中）。
As it stands now, there's nothing. Just the partially filled out PDF I passed in below as base64 data, with none of the server template tabs to fill out or sign. Here's my json for the API call (in PHP).
$data = array (
"emailBlurb" => "Test Email Body",
"emailSubject" => "Test Email Subject",
"status" => "sent",
"compositeTemplates" => array(array(
"document" => array(
"documentId" => 46677269,
"name" => $documentName,
"documentBase64" => $document
),
"serverTemplates" => array(array(
"sequence" => 1,
"templateId" => "_redacted_"
)),
"inlineTemplates" => array(array(
"sequence" => 2,
"recipients" => array(
"signers" => array(array(
"email" => $recipientEmail,
"name" => $recipientName,
"recipientId" => $recipientID,
"roleName" => "New Employee"
))
)
))
))
); //$data = array...
我怀疑我只是缺少一些适当的参考服务器模板中定义的标签。但是文档非常糟糕，我已经花了几个小时来整理网络。任何帮助将非常感激。
I suspect that I'm simply missing some appropriate reference to the tabs defined in the server template. But documentation is atrocious and I've already spent several hours combing the web. Any help would be much appreciated.
UPDATE1
根据要求，以下是成功生成信封的代码：
As requested, here's the code that generates the envelope successfully:
function c_requestSignature($templateID, $recipientName, $recipientEmail, $recipientID, $document){
//function sets up the passed document for signing using the specified template
$documentName = "W4"; //FIXME fetch document name using templateID
$baseURL = c_docusignBaseURL();
$accountId = c_docusignAccountId();
$header = c_docusignHeader();
$data = array (
"emailSubject" => "Please sign " . $documentName,
//"emailBlurb" => "Test Email Body",
"status" => "sent",
"compositeTemplates" => array(
"compositeTemplate" => array(
"serverTemplates" => array(
"serverTemplate" => array(
"sequence" => "1",
"templateId" => "_redacted_"
)
),
"inlineTemplates" => array(
"inlineTemplate" => array(
"sequence" => "2",
"recipients" => array(
"signers" => array(
"signer" => array(
"name" => $recipientName,
"email" => $recipientEmail,
"roleName" => "NewHire"
)
)
)
)
),
"document" => array(
"documentId" => "1",
"name" => $documentName,
"fileExtension" => "pdf",
"documentBase64" => $document
)
)
)
);
// Send to the /envelopes end point, which is relative to the baseUrl received above.
$curl = curl_init($baseURL . "/envelopes" );
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string),
"X-DocuSign-Authentication: $header" )
);
$json_response = curl_exec($curl); // Do it!
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ( $status != 201 ) {
echo "Error calling DocuSign, status is:" . $status . "\nerror text: ";
print_r($json_response); echo "\n";
exit(-1);
}
$response = json_decode($json_response, true);
$envelopeId = $response["envelopeId"];
error_log ("successfully created envelope: $envelopeId");
$url = getSignatureURL($envelopeId, $recipientName, $recipientEmail, $recipientID);
return $url;
}//c_requestSignature()...
函数getSignatureURL（）的代码为
The function getSignatureURL() has code as follows:
function getSignatureURL($envelopeId, $recipientName, $recipientEmail, $recipientID){
//function retrieves the signing ceremony UX URL from DocuSign
$baseURL = c_docusignBaseURL();
$accountId = c_docusignAccountId();
$header = c_docusignHeader();
//set up the data we'll send to the Docusign server
$data = array("returnUrl" => "http://_redacted_",
"authenticationMethod" => "none",
"email" => $recipientEmail,
"name" => $recipientName,
"recipientId" => $recipientID,
//"recipientId" => "1",
//"clientUserId" => $recipientID,
"userName" => $recipientName
);
$data_string = json_encode($data);
//set up curl
$curl = curl_init($baseURL . "/envelopes/$envelopeId/views/recipient" );
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($data_string),
"X-DocuSign-Authentication: $header" )
);
//make the API call
$json_response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ( $status != 201 ) {
echo "error calling webservice, status is:" . $status . "\nerror text is --> ";
print_r($json_response); echo "\n";
exit(-1);
}
//retrieve and process the response
$response = json_decode($json_response, true);
return $response["url"];
}
更新2
这是请求的原始json ...
Here's the raw json as requested...
{
"emailSubject": "some subject",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "_redacted_"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Andrew Tester1",
"email": "my_email_address",
"roleName": "NewHire",
"recipientId": "1234",
"clientUserId": "1234"
}
]
}
}
],
"document": {
"documentId": "1",
"name": "W4",
"fileExtension": "pdf",
"documentBase64": "_redacted_"
}
}
]
}
更新3
我遇到了一个问题，使我无法看到正确的输出上面的json。修复该错误之后，现在出现以下错误：
I had a problem which was preventing me from seeing the proper output of the above json. With that fixed, now I'm getting the following error:
调用DocuSign时出错，状态为：400错误文本：{ errorCode ：
TAB_REFERS_TO_MISSING_DOCUMENT，消息：在tab元素中指定的
的DocumentId不在此信封中引用文档。在
索引中不存在的DocumentId 46677269。 }
Error calling DocuSign, status is:400 error text: { "errorCode": "TAB_REFERS_TO_MISSING_DOCUMENT", "message": "The DocumentId specified in the tab element does not refer to a document in this envelope. Tab refers to DocumentId 46677269 which is not present." }
如果我按如下方式更改文档节：
If I change the document stanza above as follows:
"document": {
"documentId": "46677269",
"name": "W4",
"fileExtension": "pdf",
"documentBase64": "_redacted_"
}
错误消失了，但是我仍然得到没有选项卡的签字仪式。
The error goes away, but I still get a signing ceremony with no tabs.
推荐答案
这是一个棘手的问题，但我终于找到了解决方案，在多库西涅（Docusign）的人们的帮助下。我认为我会在这里发布它，以供将来可能会遇到此问题的人使用。
Well this was a thorny problem, but I found the solution (finally), with some help form the folk at Docusign. I thought I'd post it here for those who might run into this in the future.
解决方案
传递给DocuSign API的json结构非常重要。如果有任何错误，将无法正常使用，并且错误消息并不总是有用。此外，在我做的事情中，传递的特定参数也很关键。上面的信封生成代码是正确的，但是要注意，您必须指定PDF文档ID，该ID是DocuSign服务器上存储的模板的一部分。您可以通过给定信封ID（这是我的工作）的API来查询。显然，这不是必需的，但现在是必需的，并且没有文档说明这一点。
Solution The json structure passed to the DocuSign API is extremely important. If there are any errors in it at all, it won't work right, and the error message is not always helpful. Furthermore, in what I was doing, the specific parameters passed were also crucial. The envelope generation code above is correct, though with the caveat that you must specify the PDF document ID that is part of the template stored on DocuSign's servers. You can query this via their API given the envelope ID (which is what I'm doing). Apparently this didn't use to be required, but now it is and there's no documentation anywhere stating that.
尽管如此，我对签名选项卡的基本问题是请求签名仪式URL的代码。我有多余的参数，这些参数被接受且没有错误，但是搞砸了。通过使用DocuSign的 REST API资源管理器生成一个有效的签名仪式URL（带有所有正确的签名选项卡），并比较输出json和我试图传递的代码。
My fundamental problem with the signature tabs though, was the code requesting the signing ceremony URL. I had extra parameters which were being accepted without error, but were messing things up. Discovered this, by using DocuSign's REST API explorer to generate a working signing ceremony URL (complete with all the proper signature tabs), and comparing the output json whith what I was trying to pass in my code.
这是可以生成正确json的有效PHP代码：
Here's the working PHP code that generates the correct json:
$data = array(
"authenticationMethod" => "email",
"clientUserId" => $recipientID,
"email" => $recipientEmail,
"returnUrl" => "_redacted_",
"userName" => $recipientName
);
$data_string = json_encode($data);
这篇关于Docusign API服务器模板本地文档和选项卡的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
