如何使用 Docusign 的 REST API 在从模板创建的信封中预填充字段？

Question

注意：我使用的是“经典”体验，因为新界面无法让模板为未来的签名者设置必填字段。

工作流程：

• 有一个包含一堆字段的模板

• 使用api：

  • 从模板创建一个信封/文档，并指定一个新用户进行签名（此文档将成为注册服务的协议）

    • 创建新角色
    • 将 roleName 设置为模板上的假签名者（因为模板上没有至少一个签名者，我无法配置字段）
    • 添加 textTabs 以尝试填充某些字段。

  • 检索收件人

  • 创建一个收件人视图，以便我获得要放入 iframe 的 URL

这有点令人讨厌，因为我不在乎有一个不是注册服务的用户的第一个签名者。但是，我希望在签名后将文档复制给某人，但 docusign 似乎不支持这一点（无论如何我已经找到了）。

这是用于创建信封的 node.js 代码（我认为我的 API 使用出错了）：

function createEnvelopeDefinition(templateId, userData) {
  var envDef = new docusign.EnvelopeDefinition();
  envDef.setEmailSubject('Signup Agreement');
  envDef.setTemplateId(templateId);

  var tRole = new docusign.TemplateRole();
  tRole.setRoleName('RoleOne');
  tRole.setName(userData.fullName);
  tRole.setEmail(userData.email);
  tRole.setClientUserId('2');
  tRole.setTabs(new docusign.Tabs());
  tRole.getTabs().setTextTabs([]);

  const fieldsToPreFill = [
    'field1',
    'field2',
    'field3',
    'field4'];

  fieldsToPreFill.forEach(fieldName => {
    let textTab = new docusign.Text();
    let value = userData[fieldName];
    if (value === null || value === undefined) { value = 'not null'; }
    textTab.setTabLabel(fieldName);
    textTab.setValue(value);
    tRole.getTabs().getTextTabs().push(textTab);
  });

  tRole = removeNulls(tRole);

  envDef.setTemplateRoles([tRole]);

  // send the envelope by setting |status| to 'sent'.
  // To save as a draft set to 'created'
  //   sent is required for getting view URLs
  envDef.setStatus('sent');

  return envDef;
}

在上的DocuSign模板编辑器中， Data Field Tag Properties显示每个的相应字段的标签field1，field2等等。

现在，当我将新信封放入 iframe 时，这些字段会用提供的值填充。

仅供参考，这里是创建 api 连接并获取视图 URL 的其余代码

import ENV from 'environment/backend';
const accountId = ENV.docusign.accountId;
var Promise = require('bluebird');

var docusign = require('docusign-esign');

export function newApiClient() {
  let apiClient = new docusign.ApiClient();
  apiClient.setBasePath(ENV.docusign.endpoint);

  // create JSON formatted auth header
  let creds = JSON.stringify({
    Username: ENV.docusign.email,
    Password: ENV.docusign.password,
    IntegratorKey: ENV.docusign.integratorKey
  });

  apiClient.addDefaultHeader('X-DocuSign-Authentication', creds);

  // assign api client to the Configuration object
  // this probably doesn't need to be set every time...
  docusign.Configuration.default.setDefaultApiClient(apiClient);

  return apiClient;
}

const defaultApiClient = newApiClient();
const envelopesApi = new docusign.EnvelopesApi();

const createEnvelope = Promise.promisify(envelopesApi.createEnvelope, { context: envelopesApi });
const listRecipients = Promise.promisify(envelopesApi.listRecipients, { context: envelopesApi });
const createRecipientView = Promise.promisify(envelopesApi.createRecipientView, { context: envelopesApi });

export default defaultApiClient;

// promise resolves to the view URL, envelopeId for the user.
// returns a recipientView
export function setupDocumentForEmbeddedSigning(templateId, userData) {
  let envDefinition = createEnvelopeDefinition(templateId, userData);

  return createEnvelope(accountId, envDefinition, null)
    .then(envelopeSummary => {
      const envelopeId = envelopeSummary.envelopeId;

      return createViewFromEnvelope(envelopeId);
    });
}

export function createViewFromEnvelope(envelopeId) {
  return getRecipients(envelopeId).then(recipients => {
    // the last signer is the one we added in the
    // createEnvelopeDefinition step
    let signers = recipients.signers;
    let lastSigner = signers[signers.length - 1];

    return createView(envelopeId, lastSigner)
      .then(recipientView => [recipientView.url, envelopeId]);
  });
}

function getRecipients(envelopeId) {
  return listRecipients(accountId, envelopeId);
}

function createView(envelopeId, signerData) {
  var viewRequest = new docusign.RecipientViewRequest();
  viewRequest.setReturnUrl(ENV.host);
  viewRequest.setAuthenticationMethod('email');

  // recipient information must match embedded recipient info
  // from the createEnvelopeDefinition method
  viewRequest.setEmail(signerData.email);
  viewRequest.setUserName(signerData.name);
  viewRequest.setRecipientId('2');
  viewRequest.setClientUserId('2');

  return createRecipientView(accountId, envelopeId, viewRequest);
}

// bug with the api wrapper
// https://github.com/docusign/docusign-node-client/issues/47
const removeNulls = function(obj) {
  var isArray = obj instanceof Array;
  for (var k in obj) {
    if (obj[k] === null) isArray ? obj.splice(k, 1) : delete obj[k];
    else if (typeof obj[k] == 'object') removeNulls(obj[k]);
    if (isArray && obj.length == k) removeNulls(obj);
  }
  return obj;
};

Answer 1

所以，我可能不完全明白你卡在哪里，但无论如何我都会尝试一下......

假设我使用 DocuSign UI 创建了一个模板并定义了两个收件人角色：

• Signer1（将是注册您的服务的人）-- Action = "Sign"
• CarbonCopy1（这将是谁得到一次完成/签署的文件副本的人Signer1标志） -行动=“收到一份”

（注意：这些角色可以随意命名——我将它们命名为“Signer1”和“CarbonCopy1”，以便清楚每个角色代表谁。）

假设上述场景，您的模板的收件人角色（在 DocuSign UI 中）将如下所示：

接下来，让我们假设您在模板的文档（即，使用 DocuSign UI）中定义了Signer1收件人在签署文档时需要填充的一些字段（选项卡）。对于此示例，我们假设这些 Text 选项卡之一的标签（名称）是field1。请注意，该字段已分配给Signer1收件人：

现在，如果我想通过使用此模板的 API 创建一个信封，并为一个或多个收件人预填充字段，那么关键是在 API 请求中使用“复合模板”结构。（请参阅复合模板的部分当前页的详细信息）。在上述的例子中，您的compositeTemplates API请求将包含一个单一的对象serverTemplate对象（其指定templateId和序列= 1），和一个单一的inlineTemplate对象（其指定序列=2 和收件人信息，包括您要预填充的任何选项卡（字段）的值）。

在上面描述的示例中，用于创建信封的 JSON API 请求将如下所示（假设我们只是为Signer1预填充单个字段——显然您可以通过简单地将附加字段包含在选项卡对象中来预填充它们请求以及field1）：

POST https://{{env}}.docusign.net/restapi//v2/accounts/{{accountId}}/envelopes

{
    "emailSubject": "Test Pre-fill Tabs",
    "emailBlurb": "This is a test.",
    "compositeTemplates": [{
        "serverTemplates": [{
            "sequence": "1",
            "templateId": "CD0E6D53-3447-4A9E-BBAF-0EB2C78E8310"
        }],
        "inlineTemplates":[{
            "sequence": "2",
            "recipients": {
                "signers": [
                    {
                        "roleName": "Signer1",
                        "recipientId": "1",
                        "name": "John Doe",
                        "email": "johndoe@test.com",
                        "clientUserId": "1234",
                        "tabs": {
                            "textTabs": [
                                {
                                    "tabLabel": "field1",
                                    "value": "TEST-123"
                                }
                            ]
                        }
                    },
                    {
                      "roleName": "CarbonCopy1",
                      "recipientId": "2",
                      "name": "Jane Doe",
                      "email": "janedoe@test.com"
                    }
                ]
            }
        }]
    }],
    "status": "sent"
}

使用上述请求创建信封后，我会执行“POST Recipient View”请求以获取第一个收件人 ( https://{{env}}.docusign.net/restapi//v2/accounts/{{accountId}}/envelopes/{{envelopeId/views/recipient)的签名 URL 。

然后，当我随后使用该响应中返回的 URL 启动Signer1（John Doe）的签名会话时，我看到field1选项卡确实预先填充了我在“创建信封”API 请求中指定的值（测试-123）：

此外，一旦 John Doe ( Signer1 ) 完成签名并提交完成的文件，Jane Doe ( CarbonCopy1 ) 将收到一份副本。

我不熟悉 DocuSign 节点 SDK，但想象一下，您可以找出使用复合模板的语法，如上例所示。希望这可以帮助！