Docusign集成调用ListStatusChange接口Recipients字段为空问题咨询

根因说明 #

EnvelopesApi.ListStatusChanges 接口默认仅返回信封基础字段（envelopeId、Status、StatusChangedDate等），不会主动加载关联的收件人资源，因此你获取到的Envelope对象中Recipients属性默认为null，和你创建信封的代码逻辑无关。

解决方案1：列表查询时指定扩展返回字段 #

调用ListStatusChanges时通过include参数显式指定要返回收件人信息即可，示例代码如下：

var envelopesApi = new EnvelopesApi();
// 配置查询参数
var listOptions = new EnvelopesApi.ListStatusChangesOptions
{
    include = "recipients", // 核心配置：要求接口返回收件人数据
    fromDate = DateTime.Now.AddDays(-30).ToString("yyyy-MM-dd") // 按需配置查询时间范围
};
// 获取带收件人信息的信封列表
var envelopeListResult = envelopesApi.ListStatusChanges(accountId, listOptions);
// 此时即可正常读取收件人信息
var firstSignerName = envelopeListResult.Envelopes.FirstOrDefault()?.Recipients?.Signers?.FirstOrDefault()?.Name;

解决方案2：单独查询指定信封的收件人 #

如果你已经拿到了信封ID，也可以单独调用收件人查询接口获取数据：

var envelopesApi = new EnvelopesApi();
// 传入对应信封ID查询收件人
var recipients = envelopesApi.ListRecipients(accountId, targetEnvelopeId);
var firstSignerName = recipients.Signers.FirstOrDefault()?.Name;

注意事项 #

• 确认调用接口使用的账号有对应信封的访问权限，权限不足时收件人字段会被脱敏返回空值
• 你提供的信封创建代码中TemplateRole的赋值逻辑没有问题，无需调整

内容的提问来源于stack exchange，提问作者Geisy Alfonso Martínez