使用DocuSign复合模板（含服务器模板）时如何为文档添加唯一标识？

解决这个问题的核心是将documentFields直接绑定到每个复合模板的document对象上——这是DocuSign官方支持的为单个文档添加自定义元数据的方式，你之前的尝试失败大概率是因为字段层级放错了位置。

一、创建信封时为每个文档添加唯一标识 #

使用Node.js SDK构建信封时，每个复合模板（CompositeTemplate）下的document对象可以直接配置documentFields，用来存储你的唯一标识。示例代码如下：

const docusign = require('docusign-esign');

// 初始化DocuSign客户端（省略客户端配置步骤）
const apiClient = new docusign.ApiClient();
apiClient.setBasePath('https://demo.docusign.net/restapi');
apiClient.addDefaultHeader('Authorization', 'Bearer YOUR_ACCESS_TOKEN');

// 构建第一个复合模板（复用服务器模板）
const compositeTemplate1 = new docusign.CompositeTemplate();
compositeTemplate1.compositeTemplateId = '1';

// 关联服务器模板
const serverTemplate1 = new docusign.ServerTemplate();
serverTemplate1.templateId = 'YOUR_SERVER_TEMPLATE_ID';
serverTemplate1.sequence = '1';
compositeTemplate1.serverTemplates = [serverTemplate1];

// 配置文档及唯一标识字段
const doc1 = new docusign.Document();
doc1.documentId = '1';
// 添加自定义唯一标识
doc1.documentFields = [
  new docusign.NameValue({
    name: 'uniqueDocId',
    value: 'ORDER-2024-001' // 替换为你的业务唯一标识
  })
];
compositeTemplate1.document = doc1;

// 添加内联模板（用于填充服务器模板的标签）
const inlineTemplate1 = new docusign.InlineTemplate();
inlineTemplate1.sequence = '2';
// 配置收件人、标签填充值等（省略具体配置）
compositeTemplate1.inlineTemplates = [inlineTemplate1];

// 构建第二个复合模板（相同服务器模板，不同唯一标识）
const compositeTemplate2 = new docusign.CompositeTemplate();
compositeTemplate2.compositeTemplateId = '2';

const serverTemplate2 = new docusign.ServerTemplate();
serverTemplate2.templateId = 'YOUR_SERVER_TEMPLATE_ID';
serverTemplate2.sequence = '1';
compositeTemplate2.serverTemplates = [serverTemplate2];

const doc2 = new docusign.Document();
doc2.documentId = '2';
doc2.documentFields = [
  new docusign.NameValue({
    name: 'uniqueDocId',
    value: 'ORDER-2024-002'
  })
];
compositeTemplate2.document = doc2;

const inlineTemplate2 = new docusign.InlineTemplate();
inlineTemplate2.sequence = '2';
// 配置另一组标签填充值
compositeTemplate2.inlineTemplates = [inlineTemplate2];

// 组装信封定义并发送
const envelopeDefinition = new docusign.EnvelopeDefinition();
envelopeDefinition.compositeTemplates = [compositeTemplate1, compositeTemplate2];
envelopeDefinition.status = 'sent';

const envelopesApi = new docusign.EnvelopesApi(apiClient);
const envelope = await envelopesApi.createEnvelope('YOUR_ACCOUNT_ID', { envelopeDefinition });

二、获取已签署文档时提取唯一标识 #

调用envelopes::listDocuments接口后，返回的每个文档对象会包含你之前设置的documentFields，直接读取即可实现唯一识别：

const envelopesApi = new docusign.EnvelopesApi(apiClient);
const docsResponse = await envelopesApi.listDocuments('YOUR_ACCOUNT_ID', envelope.envelopeId);

// 遍历文档，根据唯一标识处理
docsResponse.envelopeDocuments.forEach(doc => {
  const uniqueIdField = doc.documentFields?.find(field => field.name === 'uniqueDocId');
  if (uniqueIdField) {
    console.log(`文档文件名: ${doc.name}, 唯一标识: ${uniqueIdField.value}`);
    // 此处根据唯一标识执行后续业务逻辑
  }
});

关键注意事项 #

• documentFields必须直接挂载在复合模板的document对象下，不能放在内联模板或服务器模板中，这是你之前尝试失败的核心原因。
• 这种方式是DocuSign官方支持的文档级元数据存储，完全可靠，不会依赖文档顺序这类不稳定因素。

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