如何使用DocuSign的REST API在从模板创建的信封中预填充域？ [英] How do I prefill fields in an envelope created from a template using Docusign's REST 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等。

现在，当我在IFRAME中抛出新信封时，这些字段将使用提供的值填充。

这里仅供参考，这里是创建接口连接并获取视图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创建了一个模板，并定义了两个收件人角色：

• 签名1(将注册您的服务的人)--操作="签名"
• CarbonCopy1(签署后获得已完成/签名文档副本的人员)--操作="接收副本"

(注意：这些角色可以命名为您想要命名的任何名称--我将它们命名为"Signer1"和"CarbonCopy1"，以便清楚每个角色代表谁。)

假设采用上述方案，模板的收件人角色(在DocuSign用户界面中)将如下所示：

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

现在，如果我想通过使用此模板的API创建信封，并为一个或多个收件人预先填充字段，关键是在API请求中使用"复合模板"结构。(有关详细信息，请参阅this page的复合模板部分。)在上面描述的示例中，API请求中的组合模板对象将包含一个serverTemplate对象(它指定templateID和序列=1)和一个内联模板对象(它指定序列=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": "[e-mail]",
                        "clientUserId": "1234",
                        "tabs": {
                            "textTabs": [
                                {
                                    "tabLabel": "field1",
                                    "value": "TEST-123"
                                }
                            ]
                        }
                    },
                    {
                      "roleName": "CarbonCopy1",
                      "recipientId": "2",
                      "name": "Jane Doe",
                      "email": "[e-mail]"
                    }
                ]
            }
        }]
    }],
    "status": "sent"
}

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

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

此外，在无名氏(签名1)完成签名并提交完成的文档后，无名氏(CarbonCopy1)将收到一份副本。

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

这篇关于如何使用DocuSign的REST API在从模板创建的信封中预填充域？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！