C#中发送DocuSign信封前如何填充PDF内已有字段

针对发送信封前预填充PDF内已有文本、复选框字段的需求，直接通过DocuSign eSignature API的原生表单域转换能力即可实现，不需要手动在DocuSign后台拖拽标签。

核心前提 #

你要操作的PDF内字段为标准AcroForm表单域（绝大多数PDF编辑器生成的表单都符合这个标准，你截图里的字段属于这类）。

关键配置 #

上传PDF到信封时，必须给文档对象设置TransformPdfFields = "true"，该参数会让DocuSign自动识别PDF内已有的所有表单域，转换为可通过API赋值的DocuSign标签，不开启这个参数所有预填充逻辑都不会生效。

实现步骤 #

• 初始化DocuSign客户端，完成Access Token鉴权
• 构建信封对象，配置签约人信息，信封状态可根据需求选sent（直接发送）或created（存草稿后续操作）
• 上传目标PDF作为信封文档，开启TransformPdfFields配置
• 按照字段类型构建对应Tab对象，TabLabel必须和PDF内原有字段的名称完全一致（大小写、空格全匹配），给对应字段赋值
• 调用创建信封接口完成发送/草稿生成

C# 代码示例（基于官方SDK） #

首先通过NuGet安装官方依赖包：DocuSign.eSign

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

public class DocusignEnvelopeTool
{
    public string SendPrefilledFormEnvelope(string accessToken, string accountId)
    {
        // 初始化API客户端，生产环境替换restapi地址为正式环境域名
        var apiClient = new ApiClient("https://demo.docusign.net/restapi");
        apiClient.Configuration.DefaultHeader.Add("Authorization", $"Bearer {accessToken}");

        // 构建信封基础配置
        var envelopeDef = new EnvelopeDefinition
        {
            EmailSubject = "请签署预填充的服务表单",
            Status = "sent",
            Documents = new List<Document>(),
            Recipients = new Recipients
            {
                Signers = new List<Signer>
                {
                    new Signer
                    {
                        Email = "signer@example.com",
                        Name = "签约人姓名",
                        RecipientId = "1",
                        Tabs = new Tabs()
                    }
                }
            }
        };

        // 上传PDF并开启原生表单域转换
        var localPdfPath = @"C:\你的表单文件.pdf";
        var formDoc = new Document
        {
            DocumentBase64 = System.Convert.ToBase64String(File.ReadAllBytes(localPdfPath)),
            Name = "医疗服务表单.pdf",
            DocumentId = "1",
            TransformPdfFields = "true" // 核心配置，必须开启
        };
        envelopeDef.Documents.Add(formDoc);

        var signerTabs = envelopeDef.Recipients.Signers[0].Tabs;
        signerTabs.TextTabs = new List<Text>();
        signerTabs.CheckboxTabs = new List<Checkbox>();

        // 预填充"Name of the facility/provider"文本字段
        var providerNameTab = new Text
        {
            TabLabel = "Name of the facility/provider", // 和PDF内字段名完全一致
            Value = "XX社区医疗服务中心", // 你要预填充的内容
            Locked = "true", // 设为true则签约人无法修改该字段，允许修改则设为false
            DocumentId = "1",
            PageNumber = "1" // 字段所在页码，从1开始计数
        };
        signerTabs.TextTabs.Add(providerNameTab);

        // 勾选"Medicaid"复选框
        var medicaidCheck = new Checkbox
        {
            TabLabel = "Medicaid", // 和PDF内复选框字段名完全一致
            Selected = "true", // true=勾选，false=不勾选
            Locked = "true",
            DocumentId = "1",
            PageNumber = "1"
        };
        signerTabs.CheckboxTabs.Add(medicaidCheck);

        // 调用接口创建并发送信封
        var envelopesApi = new EnvelopesApi(apiClient);
        var result = envelopesApi.CreateEnvelope(accountId, envelopeDef);
        return result.EnvelopeId;
    }
}

常见问题排查 #

• 预填充不生效：优先检查TransformPdfFields是否设为"true"，再核对TabLabel和PDF内字段名是否完全匹配。如果不确定字段名，可先创建一个status=created的草稿信封，调用ListTabs接口拉取该文档下所有自动识别的标签，即可拿到准确的字段名。
• 复选框无法勾选：部分PDF生成的复选框导出值不是默认的"Yes"，可通过ListTabs接口查看对应复选框的CheckboxStateValue属性，赋值时匹配对应值即可。
• 预填充内容被签约人篡改：将对应Tab的Locked属性设为"true"即可锁定字段，不允许签约人编辑。

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