使用模板创建DocuSign信封时出现NO_DOCUMENT_RECEIVED错误

这个错误的核心原因是你的请求结构没有正确声明使用模板创建信封，DocuSign API默认会认为你要上传新的Base64编码文档，因此抛出该错误。结合你的场景（预览正常，说明模板本身有效），可以从以下几个方面排查修复：

排查与修复步骤 #

1. 确保请求顶层包含templateId并设置status: "sent" #

创建信封的请求必须在顶层直接传入templateId，同时将status设为sent（否则信封只会创建不会发送）。不要将templateId嵌套在子对象中，也不要遗漏这两个关键字段。

正确的请求结构示例：

{
  "templateId": "你的有效模板ID",
  "status": "sent",
  "templateRoles": [
    {
      "email": "收件人邮箱",
      "name": "收件人姓名",
      "roleName": "模板内定义的角色名", // 必须与模板角色完全匹配（大小写敏感）
      "recipientId": "1"
    }
  ],
  "ccRecipients": [
    {
      "email": "抄送用户邮箱",
      "name": "抄送用户姓名",
      "recipientId": "2"
    }
  ],
  "customFields": {
    "textCustomFields": [
      {
        "name": "自定义字段名",
        "value": "字段值"
      }
    ]
  }
}

2. 移除无效的documents数组 #

如果你的请求中包含documents字段但内容为空，或者未正确关联模板，DocuSign会判定你需要上传新文档。确保请求中不要包含空的documents数组，除非你确实需要在模板基础上添加额外文档。

3. 严格匹配模板角色名 #

templateRoles中的roleName必须和你在DocuSign后台创建模板时定义的角色名完全一致（包括大小写）。角色名不匹配会导致DocuSign无法识别模板收件人，进而触发默认的文档上传要求。

4. 验证API端点与请求头 #

• 使用正确的创建信封端点：/v2.1/accounts/{accountId}/envelopes，不要和模板预览的端点混淆。
• 请求头必须设置Content-Type: application/json，否则参数解析会出错，导致templateId无法被正确识别。

Next.js代码示例 #

async function createAndSendEnvelope() {
  const accountId = process.env.DOCUSIGN_ACCOUNT_ID;
  const accessToken = await getDocusignAccessToken(); // 替换为你的token获取逻辑

  const envelopePayload = {
    templateId: "YOUR_TEMPLATE_ID",
    status: "sent",
    templateRoles: [
      {
        email: "recipient@example.com",
        name: "收件人姓名",
        roleName: "模板角色名",
        recipientId: "1"
      }
    ],
    ccRecipients: [
      {
        email: "cc@example.com",
        name: "抄送用户姓名",
        recipientId: "2"
      }
    ],
    customFields: {
      textCustomFields: [
        { name: "订单编号", value: "ORD-2024001" }
      ]
    }
  };

  const res = await fetch(`https://demo.docusign.net/restapi/v2.1/accounts/${accountId}/envelopes`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(envelopePayload)
  });

  if (!res.ok) {
    const errorData = await res.json();
    console.error("创建信封失败:", errorData);
    return;
  }

  const envelopeInfo = await res.json();
  console.log("信封发送成功，ID:", envelopeInfo.envelopeId);
}

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