DocuSign Node.js SDK填充prefillTabs调用createDocumentTabs报错问题

当前实现流程在第5步执行失败，流程如下：

• 从项目数据库拉取数据
• 完成DocuSign身份认证，获取accountId
• 基于模板创建信封草稿，配置参数{status: "created"}，已在账号中确认草稿成功生成
• 获取envelopeId
• 传入accountId和envelopeId调用envelopeAPI.createDocumentTabs编辑字段

调用上述接口始终返回"Bad Request"错误，无法确认是否为接口选型错误。

失败代码段 #

if (envelopeId) {
  console.log(accountId, envelopeId, tabs);
  const res = await envelopesApi
    .createDocumentTabs(accountId, envelopeId, '1', getTabs("hello"));
  console.log(res);
}

getTabs(projName: string)函数中测试过的所有参数格式均调用失败，测试写法如下：

写法A #

const prefillTabs = {
        textTabs: [
          {
            'anchorString': '/koujimei/',
            'anchorUnits': 'pixels',
            'anchorXOffset': '20',
            'anchorYOffset': '10',
            'scaleValue': '1.5',
            'name': 'projName',
            'value': projName,
          },
        ],
      };
      return JSON.stringify(prefillTabs)

写法B（曾认为符合官方文档要求） #

const prefillTabs = {
  prefillTabs: {
    textTabs: [
      {
        'anchorString': '/koujimei/',
        'anchorUnits': 'pixels',
        'anchorXOffset': '20',
        'anchorYOffset': '10',
        'scaleValue': '1.5',
        'name': 'projName',
        'value': projName,
      },
    ],
  },
};
return JSON.stringify(prefillTabs);

写法C #

const prefillTabs = {
  tabs: {
    prefillTabs: {
      textTabs: [
        {
          'anchorString': '/koujimei/',
          'anchorUnits': 'pixels',
          'anchorXOffset': '20',
          'anchorYOffset': '10',
          'scaleValue': '1.5',
          'name': 'projName',
          'value': projName,
        },
      ],
    },
  },
};
return JSON.stringify(prefillTabs);

其他已尝试的无效方案：

• 不做stringify处理直接传入对象，TypeScript提示该参数要求为字符串类型
• 省略第4个可选参数调用，依然返回"Bad Request"错误，对应代码：

const res = await envelopesApi
  .createDocumentTabs(accountId, envelopeId, '1');

解决方案 #

核心错误 #

调用的API选型完全错误。createDocumentTabs的作用是给文档新增归属签署人的自定义标签，不支持操作prefillTabs（预填充标签）；且prefillTabs不支持在草稿创建后单独追加编辑，必须在信封创建环节同步传入。

正确实现方式 #

1. 废弃「先创建草稿再单独调用接口改标签」的流程，prefillTabs在调用createEnvelope生成信封时直接配置在对应模板角色参数中即可，无需后续单独调用标签编辑接口。
2. Node.js SDK会自动处理参数序列化，不需要手动执行JSON.stringify，TS类型提示异常优先检查本地SDK版本与类型定义版本是否匹配。正确的参数结构参考：

const envelopeDefinition = {
  status: "created", // 可根据需求改为sent
  templateId: "替换为实际模板ID",
  templateRoles: [
    {
      email: "signer@example.com",
      name: "签署人姓名",
      roleName: "模板中配置的对应角色标识", // 必须和模板内配置的角色名完全一致
      tabs: {
        prefillTabs: {
          textTabs: [
            {
              anchorString: '/koujimei/',
              anchorUnits: 'pixels',
              anchorXOffset: 20,
              anchorYOffset: 10,
              name: 'projName',
              value: projName,
              locked: true // 预填充字段建议加锁，避免签署人修改
            }
          ]
        }
      }
    }
  ]
};
// 直接调用创建信封接口传入配置即可
const result = await envelopesApi.createEnvelope(accountId, {envelopeDefinition});

注意事项 #

• 不推荐使用scaleValue控制字段大小，直接指定fontSize等标准属性即可。
• prefillTabs是发件人预设的全局只读字段，不属于任何签署人；如果需要填充的是对应签署人待确认/填写的字段，不要放在prefillTabs下，直接放在对应角色的普通标签分类（如textTabs、numberTabs）下即可，同样在创建信封时传入。
• 若确实需要修改已生成草稿的标签，使用updateEnvelopeTabs接口而非createDocumentTabs，参数结构和上述一致，直接传入JS对象即可，无需手动序列化。

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