如何通过DocuSign API将信封转为模板并保留收件人姓名与邮箱

初始信封收件人 #

带有特定姓名/邮箱的收件人，示例：

Oliver Test
oliver.test@test.com

转模板的API调用详情 #

• 请求方式：POST
• 请求地址：https://demo.docusign.net/restapi/v2.1/accounts/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx/templates

请求示例：

{
    "EnvelopeID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "name": "Basic Example",
    "emailSubject": "Template Subject",
    "envelopeTemplateDefinition": {
      "name": "Template Name",
      "shared": "true",
      "description": "Template Description",
      "recipients": {
        "signers": [
          {
            "name": "Oliver Test",
            "email": "soliver.test@test.com",
            "roleName": "Staff 1"
          }
        ]
      },
      "documents": [
        {
          "documentId": "1",
          "name": "Document Name"
        }
      ]
    }
}

当前问题 #

调用上述API将信封转为模板后，生成的模板收件人仅显示通用名称，无邮箱地址，示例：

Signer 1

疑问 #

能否在通过API将信封转为模板的过程中保留或设置收件人的姓名、邮箱及角色？

期望结果 #

生成的模板收件人需同时显示角色名、姓名和邮箱，示例：

Staff 1
Oliver Test
oliver.test@test.com

可以实现，关键是调整API请求的配置，确保收件人信息正确映射，具体操作如下：

1. 修正请求参数错误 #

你的请求示例中邮箱字段写成了soliver.test@test.com，与原收件人邮箱oliver.test@test.com不符，这类拼写错误会导致模板无法关联正确的收件人信息，需先修正。

2. 明确关联收件人信息 #

如果要手动设置收件人，需在signers数组中完整填写roleName、name、email字段，若原信封收件人有指定recipientId，建议加上该字段明确关联，避免匹配错误。

调整后的正确请求示例：

{
    "EnvelopeID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "name": "Basic Example",
    "emailSubject": "Template Subject",
    "envelopeTemplateDefinition": {
      "name": "Template Name",
      "shared": "true",
      "description": "Template Description",
      "recipients": {
        "signers": [
          {
            "name": "Oliver Test",
            "email": "oliver.test@test.com",
            "roleName": "Staff 1",
            "recipientId": "1" // 关联原信封的收件人ID（若有）
          }
        ]
      },
      "documents": [
        {
          "documentId": "1",
          "name": "Document Name"
        }
      ]
    }
}

3. 直接继承原信封收件人（更简便） #

若原信封已配置好收件人信息，可添加inheritRecipients: true参数，直接继承原信封的收件人角色、姓名和邮箱，无需手动重复填写：

{
    "EnvelopeID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
    "name": "Basic Example",
    "emailSubject": "Template Subject",
    "inheritRecipients": true, // 开启原信封收件人继承
    "envelopeTemplateDefinition": {
      "name": "Template Name",
      "shared": "true",
      "description": "Template Description",
      "documents": [
        {
          "documentId": "1",
          "name": "Document Name"
        }
      ]
    }
}

通过以上两种方式，生成的模板即可保留或设置收件人的角色、姓名和邮箱，达到期望结果。

内容的提问来源于stack exchange，提问作者engagedDev