如何将DocuSign的TemplateRoles信封转为带SMS认证的CompositeTemplates并保留文档替换功能？

要实现保留原TemplateRoles的文档替换功能（用信封文档覆盖模板文档），同时添加SMS认证，你需要调整CompositeTemplates的文档配置，确保Inline模板中的文档与服务器模板的文档ID匹配，从而触发替换逻辑而非新增文档。

关键调整点 #

• 文档ID匹配：Inline模板中上传的文档documentId必须与服务器模板（原模板）中的目标文档ID完全一致，DocuSign会自动用新文档替换模板中对应ID的文档。
• 继承签署顺序：保持收件人的roleName与模板角色一致，系统会自动沿用模板中设置的签署顺序。
• 保留原有配置：迁移原notification、emailSubject、emailBlurb等全局配置到CompositeTemplates结构中。

修正后的EnvelopeDefinition JSON示例 #

{
  "compositeTemplates": [
    {
      "serverTemplates": [
        {
          "sequence": "1",
          "templateId": "55eef358-8081-4335-92bb-5d9298197093"
        }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "documents": [
            {
              "documentBase64": "[base64]",
              "documentId": "1", // 与模板中的文档ID一致，触发替换
              "fileExtension": "pdf",
              "name": "doc1.pdf"
            }
          ],
          "recipients": {
            "signers": [
              {
                "email": "jane.smith@example.net",
                "name": "Jane Smith",
                "roleName": "Manager", // 匹配模板角色，继承签署顺序
                "recipientId": "1",
                "emailNotification": {
                  "emailBody": "Dear sir/madam, please sign upon agreement",
                  "emailSubject": "TEST signature request DocuSign",
                  "supportedLanguage": "en"
                },
                "identityVerification": {
                  "workflowId": "d9212359-89fb-42a2-a96e-d6019481bb62",
                  "inputOptions": [
                    {
                      "name": "phone_number_list",
                      "valueType": "PhoneNumberList",
                      "phoneNumberList": [
                        {
                          "countryCode": "55",
                          "number": "12345678901"
                        }
                      ]
                    }
                  ]
                }
              },
              {
                "email": "john.smith@example.com",
                "name": "John Smith",
                "roleName": "Candidate", // 匹配模板角色，继承签署顺序
                "recipientId": "2",
                "emailNotification": {
                  "emailBody": "Dear sir/madam, please sign upon agreement",
                  "emailSubject": "TEST signature request DocuSign",
                  "supportedLanguage": "en"
                },
                "identityVerification": {
                  "workflowId": "d9212359-89fb-42a2-a96e-d6019481bb62",
                  "inputOptions": [
                    {
                      "name": "phone_number_list",
                      "valueType": "PhoneNumberList",
                      "phoneNumberList": [
                        {
                          "countryCode": "55",
                          "number": "12345678902"
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ],
  "emailSubject": "TEST signature request DocuSign",
  "emailBlurb": "Dear sir/madam, please sign upon agreement",
  "notification": {
    "expirations": {
      "expireAfter": "2",
      "expireEnabled": "True",
      "expireWarn": "0"
    },
    "reminders": {
      "reminderDelay": "1",
      "reminderEnabled": "True",
      "reminderFrequency": "0"
    }
  },
  "status": "sent"
}

逻辑说明 #

1. 文档替换：通过documentId匹配，Inline模板的文档会完全替换服务器模板中同ID的文档，签署时仅显示替换后的文档，与原TemplateRoles行为一致。
2. 签署顺序：因为收件人roleName与模板角色一一对应，DocuSign会自动沿用模板中预设的角色签署顺序。
3. SMS认证：通过identityVerification字段为每个签署人配置SMS验证流程，不影响原有功能。

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