node.js - DocuSign 嵌入式签名 API

Question

两部分问题:

我们正在尝试接收文档已准备好签署的通知(我们并不完全清楚通知中提供的内容)。我们不想做电子邮件通知；我们想关闭那些。我们假设嵌入式签名的信息包含在非电子邮件通知中。有没有一种简单的方法可以向另一个程序发送推送通知，表明文档已准备好发送，如果是这样，跟进通知以进行签名 API POST 并从 DocuSign 请求信息的最佳方法是什么？

在我们的测试中，我们已经能够通过 API 调用接收嵌入的签名 URL，但它会将我们带到一个页面，该页面指向未显示选项卡的签名 View ；这意味着签名者不能签名，对于其他角色也是如此。这与 this 中解释的问题相同在大多数情况下，SO post。我正在用 JavaScript 编码，而不是 PHP。我不知道这是否会对回答问题产生影响，如果是这样，请在评论中提出更多问题，我可以提供更多信息。

这就是我们得到的，但我们应该得到一个包含签名标签的文档

这是我们应该看到的。我们在手动登录 DS 并单击文档时看到此版本。

我们认为 templateRoleName 字段可能是导致此问题的原因，但我们已经测试了使用和不使用它，它似乎没有什么不同。

这是我们在演练中使用的 API 调用的 JS 文件。

//
// to run this sample
//  1. copy the file in your own directory - say, example.js
//  2. change "***" to appropriate values
//  3. install async and request packages
//     npm install async
//     npm install request
//  4. execute
//     node example.js 
// 

var     async = require("async"),       // async module
    request = require("request"),       // request module
    email = "email@email.com",              // your account email
    password = "password1",         // your account password
    integratorKey = "DEEZ-010ebc24-01cc-143a-98c3-d9dbf7561cb1",            // your account Integrator Key (found on Preferences -> API page)
    recipientName = "email@email.com",          // recipient (signer) name
    templateId = "1C504DBA-B03F-4E57-B6BB-FD2ABD15837C",            // provide valid templateId from a template in your account
    templateRoleName = "Signer",        // template role that exists on template referenced above
    baseUrl = "",               // we will retrieve this
    envelopeId = "bc14310c-57c0-4168-91be-1fb71ea24c1c";            // created from step 2

async.waterfall(
    [
        //////////////////////////////////////////////////////////////////////
        // Step 1 - Login (used to retrieve accountId and baseUrl)
        //////////////////////////////////////////////////////////////////////
        function(next) {
            var url = "https://demo.docusign.net/restapi/v2/login_information";
            var body = "";  // no request body for login api call

            // set request url, method, body, and headers
            var options = initializeRequest(url, "GET", body, email, password);

            // send the request...
            request(options, function(err, res, body) {
                if(!parseResponseBody(err, res, body)) {
                    return;
                }
                baseUrl = JSON.parse(body).loginAccounts[0].baseUrl;
                next(null); // call next function
            });
        },

        //////////////////////////////////////////////////////////////////////
        // Step 2 - Send envelope with one Embedded recipient (using clientUserId property)
        //////////////////////////////////////////////////////////////////////
        function(next) {
            var url = baseUrl + "/envelopes";
            var body = JSON.stringify({
                "emailSubject": "DocuSign API call - Embedded Sending Example",
                "templateId": templateId,
                "templateRoles": [{
                    "email": email,
                    "name": recipientName,
                    "roleName": templateRoleName,
                    "clientUserId": "1001"  // user-configurable
                }],
                "status": "sent"
            });

            // set request url, method, body, and headers
            var options = initializeRequest(url, "POST", body, email, password);

            // send the request...
            request(options, function(err, res, body) {
                if(!parseResponseBody(err, res, body)) {
                    return;
                }
                // parse the envelopeId value from the response
                envelopeId = JSON.parse(body).envelopeId;
                next(null); // call next function
            });
        },

        //////////////////////////////////////////////////////////////////////
        // Step 3 - Get the Embedded Signing View (aka the recipient view)
        //////////////////////////////////////////////////////////////////////
        function(next) {
            var url = baseUrl + "/envelopes/" + envelopeId + "/views/recipient";
            var method = "POST";
            var body = JSON.stringify({
                "returnUrl": "http://www.docusign.com/devcenter",
                "authenticationMethod": "email",
                "email": email,
                "userName": recipientName,
                "clientUserId": "1001", // must match clientUserId in step 2!
            });

            // set request url, method, body, and headers
            var options = initializeRequest(url, "POST", body, email, password);

            // send the request...
            request(options, function(err, res, body) {
                if(!parseResponseBody(err, res, body))
                    return;
                else
                    console.log("\nNavigate to the above URL to start the Embedded Signing workflow...");
            });
        }
    ]);

    //***********************************************************************************************
    // --- HELPER FUNCTIONS ---
    //***********************************************************************************************
    function initializeRequest(url, method, body, email, password) {
        var options = {
            "method": method,
            "uri": url,
            "body": body,
            "headers": {}
        };
        addRequestHeaders(options, email, password);
        return options;
    }

    ///////////////////////////////////////////////////////////////////////////////////////////////
    function addRequestHeaders(options, email, password) {
        // JSON formatted authentication header (XML format allowed as well)
        dsAuthHeader = JSON.stringify({
            "Username": email,
            "Password": password,
            "IntegratorKey": integratorKey  // global
        });
        // DocuSign authorization header
        options.headers["X-DocuSign-Authentication"] = dsAuthHeader;
    }

    ///////////////////////////////////////////////////////////////////////////////////////////////
    function parseResponseBody(err, res, body) {
        console.log("\r\nAPI Call Result: \r\n", JSON.parse(body));
        if( res.statusCode != 200 && res.statusCode != 201) { // success statuses
            console.log("Error calling webservice, status is: ", res.statusCode);
            console.log("\r\n", err);
            return false;
        }
        return true;
    }

编辑 这是此模板的 DocuSign 经典 View 中的收件人和路由部分，因为它是此问题的原始帖子

这是请求日志中的 Created_RequestRecipientToken 文件:

POST https://demo.docusign.net:7802/restapi/v2/accounts/1037192/envelopes/deez83c9-b1fg-46ab-bo0c-e4576d952ac6/views/recipient
Content-Length: 185
Connection: keep-alive
Host: demo.docusign.net
X-DocuSign-Authentication: {"Username":"sender@email.com","Password":"[omitted]","IntegratorKey":"[omitted]"}
X-Forwarded-For: 543.155.155.55

{"returnUrl":"http://www.docusign.com/devcenter","authenticationMethod":"email","email":"sender@email.com","userName":"signer@email.com","clientUserId":"1002"}
201 Created
Content-Type: application/json; charset=utf-8

{
  "url": "https://demo.docusign.net/Signing/startinsession.aspx?t=3c06d2a3-e521-4e52-b669-01e24c81c3bf"
}

这是请求日志中的 Created_CreateEnvelopeFromTemplateAndForms 文件:

POST https://demo.docusign.net:7802/restapi/v2/accounts/1037192/envelopes
Content-Length: 272
Connection: keep-alive
Host: demo.docusign.net
X-DocuSign-Authentication: {"Username":"sender@email.com","Password":"[omitted]","IntegratorKey":"[omitted]"}
X-Forwarded-For: 143.115.155.55

{"emailSubject":"DocuSign API call - Embedded Sending Example","templateId":"9AF271E2-D38E-4E61-8083-928A3CCE056C",
"templateRoles":[{"email":"sender@email.com","name":"signer@email.com","roleName":"Signer","clientUserId":"1002"}],
"status":"sent"}
201 Created
Content-Type: application/json; charset=utf-8

{
  "envelopeId": "deez83c9-b1fg-46ab-bo0c-e4576d952ac6",
  "uri": "/envelopes/deez83c9-b1fg-46ab-bo0c-e4576d952ac6",
  "statusDateTime": "2015-07-08T15:56:23.5930000Z",
  "status": "sent"
}

this或 this或 this不是这篇文章的解决方案。

Answer 1

当您从模板发送签名请求时，如果您希望收件人继承您之前创建的所有选项卡和工作流，那么您必须将它们与角色匹配。要匹配它们，您需要使用 roleName 属性，该属性是通过您引用的 templateRoleName 示例 Node 脚本设置的。

首先，我想提一下，在您的第一个屏幕截图中没有选项卡，收件人仍然可以通过将任何选项卡从左侧拖动到文档上来签名。这称为自由形式签名，当它们与模板角色不匹配时，他们会选择将哪些选项卡、多少以及将它们放置在文档中的什么位置。

我在您的代码中看到您正在将模板角色名称设置为值 Signer，这只有在您在 Web 控制台中为占位符(模板)角色命名时才有效创建它。将 Web 控制台中角色名称的值更改为 Signer，它应该可以工作。