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

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

工作流程：

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

• 使用 API：

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

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

  • 检索收件人

  • 创建一个收件人视图，以便我获取要放入 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, etc.

当我将新信封放入 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;
};

所以，我可能不完全理解你被困在哪里，但无论如何我都会尝试一下......

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

• Signer1（这将是注册您的服务的人）--Action=“签名”
• 复写1（一旦获得完整/签署的文件副本的人Signer1标志）——Action=“接收副本”

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

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

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

现在，如果我想通过使用此模板的 API 创建一个信封，并为一个或多个收件人预填充字段，那么关键是在 API 请求中使用“复合模板”结构。 （参见复合模板的部分这一页 https://docs.docusign.com/esign/restapi/Envelopes/Envelopes/create/了解详细信息。）在上述示例中，您的复合模板API 请求中的对象将包含一个服务器模板对象（指定模板ID and sequence=1), 和一个内联模板对象（指定sequence=2 和收件人信息，包括您想要预填充的任何选项卡（字段）的值。

在上面描述的示例中，创建信封的 JSON API 请求将如下所示（假设我们只是预填充单个字段Signer1-- 显然，您可以通过简单地将附加字段包含在tabs请求的对象以及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": "[email protected] /cdn-cgi/l/email-protection",
                        "clientUserId": "1234",
                        "tabs": {
                            "textTabs": [
                                {
                                    "tabLabel": "field1",
                                    "value": "TEST-123"
                                }
                            ]
                        }
                    },
                    {
                      "roleName": "CarbonCopy1",
                      "recipientId": "2",
                      "name": "Jane Doe",
                      "email": "[email protected] /cdn-cgi/l/email-protection"
                    }
                ]
            }
        }]
    }],
    "status": "sent"
}

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

然后，当我随后使用该响应中返回的 URL 来启动签名会话时Signer1（约翰·多伊），我看到field1选项卡确实预先填充了我在“创建信封”API 请求中指定的值（TEST-123):

此外，一旦约翰·多伊（Signer1) 完成签名并提交完整的文件，Jane Doe (复写1）将发送一份副本。

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