如何用C#代码预填充PDF的first name字段并集成DocuSign流程？

要实现预填充PDF的first name字段并发起DocuSign签署流程，需要补充信封（Envelope）构建逻辑和收件人视图请求方法，以下是完整代码实现：

1. 完整代码实现 #

using DocuSign.eSign.Api;
using DocuSign.eSign.Client;
using DocuSign.eSign.Model;
using System.Collections.Generic;

public class DocuSignIntegrationService
{
    public (string envelopeId, string redirectUrl) CreateEnvelopeAndInitiateSigning(
        string basePath, 
        string accessToken, 
        string accountId, 
        string signerEmail, 
        string signerName, 
        string returnUrl, 
        string signerClientId, 
        string pingUrl,
        string pdfFilePath,
        string firstNameValue) // 要预填充的first name值
    {
        // 初始化DocuSign客户端
        var docuSignClient = new DocuSignClient(basePath);
        docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);

        // 构建信封对象，包含预填充字段和签署人信息
        EnvelopeDefinition envelope = BuildEnvelopeWithPreFillField(pdfFilePath, signerEmail, signerName, firstNameValue);

        EnvelopesApi envelopesApi = new EnvelopesApi(docuSignClient);
        EnvelopeSummary results = envelopesApi.CreateEnvelope(accountId, envelope);
        string envelopeId = results.EnvelopeId;

        // 创建收件人视图（签署仪式入口）
        RecipientViewRequest viewRequest = MakeRecipientViewRequest(signerEmail, signerName, returnUrl, signerClientId, pingUrl);
        ViewUrl results1 = envelopesApi.CreateRecipientView(accountId, envelopeId, viewRequest);

        // 返回信封ID和签署跳转链接
        string redirectUrl = results1.Url;
        return (envelopeId, redirectUrl);
    }

    // 构建包含预填充字段的信封
    private EnvelopeDefinition BuildEnvelopeWithPreFillField(string pdfFilePath, string signerEmail, string signerName, string firstNameValue)
    {
        // 读取PDF文件作为文档
        byte[] fileBytes = System.IO.File.ReadAllBytes(pdfFilePath);
        Document doc = new Document
        {
            DocumentBase64 = System.Convert.ToBase64String(fileBytes),
            Name = "待签署表单.pdf",
            FileExtension = "pdf",
            DocumentId = "1" // 文档ID需唯一
        };

        // 定义预填充字段（对应PDF中的first name字段）
        Text tab = new Text
        {
            TabLabel = "first name", // 必须严格匹配PDF表单字段的名称
            Value = firstNameValue, // 预填充的值
            DocumentId = "1",
            PageNumber = "1" // 字段所在页码，根据实际情况调整
        };

        // 定义签署人
        Signer signer = new Signer
        {
            Email = signerEmail,
            Name = signerName,
            ClientUserId = signerClientId, // 嵌入式签署必填，需与视图请求值一致
            RecipientId = "1"
        };

        // 将预填充字段关联到签署人
        signer.Tabs = new Tabs { TextTabs = new List<Text> { tab } };

        // 组装信封定义
        EnvelopeDefinition envelope = new EnvelopeDefinition
        {
            EmailSubject = "请签署您的表单",
            Documents = new List<Document> { doc },
            Recipients = new Recipients { Signers = new List<Signer> { signer } },
            Status = "sent" // 设置为sent直接发起流程，created则为草稿状态
        };

        return envelope;
    }

    // 实现收件人视图请求方法
    private RecipientViewRequest MakeRecipientViewRequest(string signerEmail, string signerName, string returnUrl, string signerClientId, string pingUrl)
    {
        RecipientViewRequest viewRequest = new RecipientViewRequest
        {
            ReturnUrl = returnUrl,
            ClientUserId = signerClientId, // 必须与签署人设置的ClientUserId一致
            AuthenticationMethod = "none", // 根据实际认证需求调整，如"email"
            UserName = signerName,
            Email = signerEmail,
            PingFrequency = "600", // 心跳间隔，单位秒
            PingUrl = pingUrl
        };

        return viewRequest;
    }
}

2. 关键注意事项 #

• 字段匹配：TabLabel必须严格匹配PDF表单中first name字段的名称，大小写敏感，特殊字符、空格需完全一致。
• ClientUserId：嵌入式签署必须设置该值，且签署人定义和视图请求中的值要保持统一。
• 文档状态：EnvelopeDefinition.Status设为sent会直接发送签署请求，设为created则保存为草稿，可后续手动触发。
• 权限配置：确保DocuSign应用拥有envelopes:create和envelopes:views:create的API权限。

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