通过DocuSign API/SDK添加信封附件失败问题排查

核心原因：信封状态限制 #

Envelope Attachments仅支持草稿（Created）或未完成发送的处理中状态，Sent状态不在支持范围内——一旦直接将信封初始状态设为Sent，添加信封附件的操作会被系统忽略，这就是你看不到附件的根本原因。

正确实现流程 #

你需要拆分两步操作：

1. 先创建草稿状态的信封，同时添加Envelope Attachments
2. 再单独调用API发送该草稿信封

修正后的代码示例 #

步骤1：创建带附件的草稿信封 #

// 构建信封定义，设置初始状态为草稿
var envelopeDefinition = new EnvelopeDefinition
{
    EmailSubject = "请签署目标文档",
    InitialStatus = "Created", // 关键：必须设为草稿状态
    Documents = new List<Document>
    {
        // 添加需要签署的文档
        new Document
        {
            DocumentId = "1",
            Name = "待签署文件.pdf",
            DocumentBase64 = Convert.ToBase64String(File.ReadAllBytes("你的文档路径"))
        }
    },
    // 配置信封附件（存储元数据）
    EnvelopeAttachments = new List<Attachment>
    {
        new Attachment
        {
            AttachmentId = "1",
            Label = "内部元数据",
            Name = "envelope-metadata.txt",
            AttachmentType = "text/plain", // 注意：需使用标准MIME类型，而非文件后缀
            Data = Convert.ToBase64String(Encoding.UTF8.GetBytes("你的内部元数据内容"))
        }
    },
    // 配置收件人信息
    Recipients = new Recipients
    {
        Signers = new List<Signer>
        {
            new Signer
            {
                Email = "signer@example.com",
                Name = "签署人姓名",
                RecipientId = "1"
            }
        }
    }
};

// 调用API创建草稿信封
var envelopesApi = new EnvelopesApi();
var envelopeSummary = envelopesApi.CreateEnvelope(accountId, envelopeDefinition);
var envelopeId = envelopeSummary.EnvelopeId;

步骤2：发送已创建的草稿信封 #

// 更新信封状态为已发送
envelopesApi.Update(accountId, envelopeId, new EnvelopeDefinition { Status = "Sent" });

关键注意事项 #

• AttachmentType字段规范：必须使用标准MIME类型（如text/plain、application/json），不能填.txt这类文件后缀，这是常见的配置错误。
• 附件验证时机：创建草稿信封后，即可调用EnvelopesApi.ListAttachments(accountId, envelopeId)确认附件已成功添加，再执行发送操作。
• 元数据后续使用：信封完成后，可通过DocuSign Connect通知中的信封ID，调用附件API获取存储的元数据。

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