DocuSign调用成功但信封状态为created而非sent问题排查

我用Node.js开发，调用DocuSign的envelopesApi.createEnvelope接口时，已经将信封的env.status设置为"sent"，接口返回成功，但返回的信封状态是"created"，指定签署人也没收到签名邮件。完整响应如下：

{
"envelopeId": "205ed07d-8094-4031-a334-7159e1bd0f34",
"status": "created",
"statusDateTime": "2023-01-05T06:19:17.9670000Z",
"uri": "/envelopes/205ed07d-8094-4031-a334-7159e1bd0f34"
}

所用模板已在UI中配置签署人角色和签名项，我试过两种操作：

1. 通过TemplateRole.constructFromObject添加签署人并设置env.templateRoles = [signer1]
2. 移除上述代码（依赖模板UI配置的签署人）
   但两种操作后，信封状态均为"created"而非"sent"。相关代码如下：

async sendEnvelopeFromTemplate(accessToken: string): Promise<any>{
  const basePath = docusign_account_base_uri + '/restapi'

  let dsApiClient = new docusign.ApiClient();
  dsApiClient.setBasePath(basePath);
  dsApiClient.addDefaultHeader("Authorization", "Bearer " + accessToken);
  let envelopesApi = new docusign.EnvelopesApi(dsApiClient);

  let envelope = this.makeEnvelope();

  try{
    let results = await envelopesApi.createEnvelope(docusign_api_account_id, {
      envelopeDefinition: envelope,
    });

    return results;
  }
  catch(e){
    console.log("ERROR")
    console.log(e)
  }

};

async makeEnvelope() {

  const args = {
    signerEmail: 'REDACTED',
    signerName: 'REDACTED',
    templateId: 'REDACTED'
  }

  let env = new docusign.EnvelopeDefinition();
  env.templateId = args.templateId;

  let signer1 = docusign.TemplateRole.constructFromObject({
    email: args.signerEmail,
    name: args.signerName,
    roleName: "signer",
  });

  env.templateRoles = [signer1];
  env.status = "sent";

  return env;
}

问题排查与解决方案 #

• 检查模板必填项是否全部填充：如果模板中存在未赋值的必填字段（比如自定义必填标签、未指定的收件人信息），DocuSign会自动将信封转为"created"草稿状态，不会发送。登录DocuSign后台查看模板配置，确认所有必填项都已在代码中正确赋值。

• 确保TemplateRole的roleName与模板角色名完全匹配：代码中roleName: "signer"必须和模板UI里配置的签署人角色名称完全一致（包括大小写、空格）。名称不匹配会导致DocuSign无法关联签署人，信封无法触发发送流程。

• 验证账号发送权限：确认调用接口使用的账号拥有发送信封的权限，部分受限账号仅能创建草稿信封，无法直接发送。

• 查看DocuSign操作日志：登录DocuSign后台，找到对应信封ID的操作日志，日志会明确标注信封未发送的具体原因（如字段缺失、权限不足等）。

• 调整TemplateRole配置示例：如果是角色名不匹配问题，修正代码中的roleName为模板实际角色名：

let signer1 = docusign.TemplateRole.constructFromObject({
  email: args.signerEmail,
  name: args.signerName,
  roleName: "模板内配置的签署人角色名", // 替换为实际角色名
});

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