无法通过C#代码预填充HelloSign自定义字段的技术问询

我来帮你排查下用C#代码预填充HelloSign自定义字段失败的问题～从你给出的代码片段来看，核心问题应该是用错了方法——GetCustomField是用来获取已存在的字段值，而不是设置预填充内容，正确的操作应该用AddCustomField方法。下面给你详细的正确实现步骤和避坑指南：

一、先确认模板里的关键配置 #

在写代码之前，你得先在HelloSign模板编辑器里搞定两件事：

1. 确保模板里的自定义字段设置了**api_id**：这是代码和模板字段匹配的唯一标识，不能用字段的显示名称（比如模板里显示“First Name”，你得给它设个api_id比如first_name）。
2. 确认签名者的角色名称：模板里定义的角色（比如“Me”“Client”）要和代码里AddSigner的角色参数完全一致（大小写、空格都不能错）。

二、正确的代码实现示例 #

using HelloSign;
using HelloSign.Api;
using HelloSign.Model;

var client = new Client("你的API密钥");
var request = new TemplateSignatureRequest();

// 添加目标模板ID
request.AddTemplate("你的文档ID");

// 设置邮件相关内容
request.Title = "Test Titel";
request.Subject = "Test Subject";
request.Message = "Test Message.";

// 添加签名者：角色名称必须和模板里的完全匹配
request.AddSigner("Me", "your-email@example.com", "Test");
request.AddSigner("Client", "client-email@example.com", "Test");

// 预填充自定义字段
// 情况1：全局自定义字段（所有签名者可见）
request.AddCustomField("first_name", "John");

// 情况2：属于特定角色的字段（比如只有Client角色能看到的地址字段）
request.AddCustomField("client_address", "123 Main St", "Client");

// 发送签名请求
try
{
    var response = client.SendTemplateSignatureRequest(request);
    Console.WriteLine("签名请求已发送，ID：" + response.SignatureRequestId);
}
catch (HelloSignException ex)
{
    // 捕获错误信息，方便排查
    Console.WriteLine($"错误信息：{ex.Message}");
    Console.WriteLine($"错误码：{ex.ErrorCode}");
}

三、常见的踩坑点 #

• 角色名称不匹配：AddSigner里的角色名称必须和模板里的角色完全一致，哪怕多一个空格或者大小写不对，都会导致字段无法关联。
• api_id错误：一定要用模板字段的api_id，而不是显示名称，比如模板里显示“客户电话”，api_id设的是client_phone，代码里就必须写client_phone。
• 字段类型不匹配：比如模板里是日期字段，要传入YYYY-MM-DD格式的字符串；数字字段要传合法的数字字符串，否则填充会失败。
• 必填字段未处理：如果模板里的自定义字段是必填项，要么预填充，要么确保签名者能手动填写，否则API请求会直接报错。

如果按照上面的步骤操作还是不行，建议捕获HelloSignException查看具体错误信息，HelloSign的API会返回非常明确的错误提示（比如“字段api_id不存在”“角色名称不匹配”），能帮你快速定位问题。

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