使用Node.js调用DocuSign API预填模板文本字段失败问题排查

我们尝试通过DocuSign预填充PDF表单，让客户只需签署模板（已具备全部表单数据）。目前能用Node.js程序化发送模板，但测试时，模板PDF中创建的名为“client-fullname”的文本字段既没被预填充，也没向签署者显示，签署者得手动拖拽字段。代码实现如下：

const tabClientFullName = docusign.Text.constructFromObject({ tabLabel: 'client-fullname', value: 'John Q Smith' });

const dsTabs = docusign.Tabs.constructFromObject({
      textTabs: [
        tabClientFullName
      ]
    });

const signer1 = docusign.TemplateRole.constructFromObject({
      email: signerEmail,
      name: signerName,
      roleName: 'signer',
      tabs: dsTabs
});

env.templateRoles = [signer1];
env.status = 'sent'; // We want the envelope to be sent

问题排查与解决要点： #

• 确认模板字段与角色绑定：在DocuSign控制台创建模板时，必须将“client-fullname”文本字段分配给代码中指定的signer角色。如果字段未关联对应角色，程序端的预填充指令无法匹配到目标字段，导致字段不显示。
• 严格匹配Tab Label：模板中字段的Tab Label必须和代码里的tabLabel: 'client-fullname'完全一致，包括大小写、符号等细节——DocuSign对Tab Label的匹配是区分大小写的，任何拼写偏差都会导致匹配失败。
• 检查字段可见性设置：确保模板中该文本字段的可见性配置为对signer角色可见。若字段被设为隐藏或仅发送者可见，签署端将无法看到该字段。
• 验证角色名称一致性：代码中roleName: 'signer'必须和模板中配置的角色名称完全匹配，模板中不存在对应角色的话，预填充操作无法生效。
• 指定文档ID和页码：如果模板包含多个文档，或者字段位于特定页面，需要在预填充字段中明确指定documentId和pageNumber，确保精准定位目标字段，示例代码如下：

const tabClientFullName = docusign.Text.constructFromObject({ 
  tabLabel: 'client-fullname', 
  value: 'John Q Smith',
  documentId: '1', // 对应模板中的文档ID
  pageNumber: '1' // 字段所在页码
});

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