如何通过收件人DocuSignAPI使用模板将accessCode发送给收件人并覆盖电子邮件？

Question

我已经尝试了所有我能想到的所有事情，并且无法使它起作用。

我试图在我的代码中设置访问代码，并使用RequestSignatureFromTemplate调用将其发送到templateRole。 现在，我所有的配置信息都是XML。 我并不反对使用JSON，但并非所有开发人员都知道JSON。

这是我的XML的片段。

<envelopeDefinition xmlns=\"http://www.docusign.com/restapi\">
    accountId>12345</accountId>
    <status>sent</status>                        
    <emailSubject>Test Form</emailSubject>
    <emailBlurb>This is a template test.</emailBlurb>
    <templateId>####-########</templateId>
    <templateRoles>
        <templateRole>
            <accessCode>AccessCode124</accessCode>" +
            <addAccessCodeToEmail>true</addAccessCodeToEmail>" +
            <email>jevans@eclarifire.com</email>
            <name>Test User</name>
            <roleName>RoleOne</roleName>
            <emailNotification>
                <emailSubject>This is RoleOne's subject</emailSubject>
                <emailBody>This is RoleOne's email.</emailBody>
                <addAccessCodeToEmail>true</addAccessCodeToEmail>
            </emailNotification>
        </templateRole>
        <templateRole>
            <accessCode>AccessCode246</accessCode>
            <email>jevans@eclarifire.com</email>
            <name>Test User2</name>
            <roleName>RoleTwo</roleName>
            <emailNotification>
                <emailBody>Your access code is 24680</emailBody>
            </emailNotification>
        </templateRole>
    </templateRoles>
</envelopeDefinition>

您会注意到，我在templateRole节点中有两种不同的实现。 这是故意的，因为我正在尝试所有我能想到的东西。 在templateRole（1）中，我在两个不同的位置添加了addAccessCodeToEmail节点，但在两个位置均不起作用。 我还尝试覆盖templateRole(1)的emailBlurb节点，它也不起作用。

我已经看完了文档，它说您应该能够添加“收件人”格式遵循的所有内容，但我无法使其正常工作。

任何人有任何想法吗？

Answer 1

我从未在“创建/发送信封” API请求中使用过addAccessCodeToEmail属性，因为收件人在接收到的电子邮件中包含访问代码，这完全抵消了使用访问代码进行身份验证的影响。 即，要求收件人输入访问代码的整个要点是增加保障的另一层 -超越的事实，有人仅仅能够访问电子邮件收件箱-授权访问信封之前。 如果您要在收件人收到的电子邮件中包含访问代码，则使用访问代码作为身份验证形式不会提供任何其他安全优势-有权访问该电子邮件收件箱的任何人都将能够轻松访问信封（与根本不使用访问代码相同的结果）。

话虽这么说， 有一个（无论何种原因）应允许您有包含在收件人收到的电子邮件访问代码属性-我不能得到这个工作的。 可能是一个错误，但DocuSign的某人需要确认。 根据文档，这将导致电子邮件中包含访问代码：

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
    "status"        : "sent",
    "emailBlurb"    : "please sign",
    "emailSubject"  : "Please sign your document",
    "templateId"    : "TEMPLATE_ID",
    "templateRoles" : [{
      "name"         : "John Doe",
      "email"        : "JohnsEmail@outlook.com",
      "roleName"     : "Signer1",
      "accessCode"   : "1234",
      "addAccessCodeToEmail": "true"
   }]
}

此请求导致收件人必须先输入访问代码，然后他才能访问信封，但是addAccessCodeToEmail属性没有达到预期的效果，因为访问代码不会出现在收件人接收的电子邮件中的任何位置。

替代方法（最佳实践） ：与使用纯文本访问代码添加到电子邮件不同，使用API​​创建/发送信封并要求访问代码作为收件人身份验证形式的最佳实践是：

• 使用您的应用程序知道的有关接收者的数据，以编程方式设置accessCode 。
• 设置“电子邮件模糊”（即电子邮件正文）以提供有关访问代码的提示。

例如，假设您的应用程序知道收件人的社会保险号。 发出“创建信封” API请求时：

• 将accessCode的值设置为收件人的SSN的最后4位数字。
• 设置emailBlurb的值以包括消息“您的访问代码是SSN的后4位”。

与仅在电子邮件本身中包括访问码（以纯文本格式）相比，以这种方式进行操作要安全得多。

最后，关于覆盖收件人的电子邮件主题和正文的问题-请参阅REST API指南第290-291页的emailNotification属性的定义（ http://www.docusign.com/sites/default/files/REST_API_Guide_v2。 pdf ）：

• 重要说明：如果为一个收件人启用了此功能，它将覆盖信封主题和EmailBlurb。 另外，您必须为所有收件人启用emailNotification 。

听起来好像您需要为每个收件人设置emailNotification，以使其生效。

Answer 2

这里有几个示例，这些示例在Create Envelope API请求中使用“复合模板”来创建具有ID检查或电话身份验证的信封作为收件人身份验证的方法。

收件人身份验证= ID检查

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "emailSubject": "Please sign",
  "emailBlurb": "Please sign...thanks!",
  "status": "sent",
  "compositeTemplates": [
  {
    "serverTemplates": [
    {
        "sequence" : 1,
        "templateId": "TEMPLATE_ID"
    }],
    "inlineTemplates": [
    {
        "sequence" : 2,
        "recipients": {
            "signers" : [{
                "email": "SallysEmail@outlook.com",
                "name": "Sally Adamson",
                "recipientId": "1",
                "roleName": "ROLE_NAME",
                "requireIdLookup": "true",
                "idCheckConfigurationName": "ID Check $"
            }]
        }
    }]
  }]  
}

收件人身份验证=电话身份验证

POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
  "emailSubject": "Please sign",
  "emailBlurb": "Please sign...thanks!",
  "status": "sent",
  "compositeTemplates": [
  {
    "serverTemplates": [
    {
        "sequence" : 1,
        "templateId": "TEMPLATE_ID"
    }],
    "inlineTemplates": [
    {
        "sequence" : 2,
        "recipients": {
            "signers" : [{
                "email": "SallysEmail@outlook.com",
                "name": "Sally Adamson",
                "recipientId": "1",
                "roleName": "ROLE_NAME",
                "requireIdLookup": "true",
                "idCheckConfigurationName": "Phone Auth $",
              "phoneAuthentication": {
                "recipMayProvideNumber": "false",
                "senderProvidedNumbers": ["206-444-5555"]
              }
            }]
        }
    }]
  }]  
}