DocuSign 嵌入式签名 API

Question

两部分问题：

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

在我们的测试中，我们已经能够通过 API 调用接收嵌入的签名 URL，但是它会将我们带到一个页面，该页面没有显示选项卡的签名视图； 这意味着签名者不能签名，对于其他角色也是如此。 大多数情况下， 这与这篇SO 帖子中解释的问题相同。 我用 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 经典视图中的收件人和路由部分，因为它是此问题的原始发布

这是请求日志中的 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"
}

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

Answer 1

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

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

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