基于C#的DocuSign API：能否获取签署人签署状态及对应文档信息？

背景与环境 #

• 需求：确定需要催促签署的对象（即未完成部分文档签署的签署人）
• 开发环境：C#，已安装DocuSign NuGet包
• 已尝试方法：
  • 调用EnvelopeAPI.ListAuditEvents(...)
  • 调用EnvelopeAPI.ListRecipients(...)，测试了单签署人多文档、多签署人单文档场景
  • 调用EnvelopeAPI.ListDocuments(...)，传入ShowFileSize=true参数但无效果

遇到的问题 #

• ListAuditEvents和ListRecipients仅能在签署人完成全部文档签署或整个信封签署完成时返回完成状态，无法获取签署人部分签署状态及对应已签署的文档信息
• ListDocuments返回的文档列表无签署状态、签署人关联信息，且传入的ListDocumentsOption参数（如ShowFileSize=true）未生效

DocuSign API支持这类细粒度信息查询，以下是具体解决方案：

1. 获取签署人部分签署状态及对应已签署文档 #

方法一：使用ListRecipients并包含标签信息 #

调用EnvelopeApi.ListRecipients时，设置include_tabs=true参数，返回的签署人对象中会包含其所有已完成的签名标签（tabs.signHereTabs），每个标签会关联对应的documentId，由此可判断该签署人已签署哪些文档。

C#代码示例：

var listRecipientsOptions = new ListRecipientsOptions
{
    IncludeTabs = "true"
};
var recipientsResponse = envelopeApi.ListRecipients(accountId, envelopeId, listRecipientsOptions);

// 遍历签署人，提取已签署文档ID
foreach (var signer in recipientsResponse.Signers)
{
    var signedDocumentIds = signer.Tabs.SignHereTabs
        .Where(tab => tab.Status == "signed")
        .Select(tab => tab.DocumentId)
        .Distinct();
    // 处理已签署文档ID列表
}

方法二：使用ListDocumentRecipients直接关联文档与签署人 #

该方法会返回每个文档对应的所有签署人状态，可直接查看特定文档哪些签署人已完成签署，或特定签署人完成了哪些文档。

C#代码示例：

var documentRecipients = envelopeApi.ListDocumentRecipients(accountId, envelopeId);

foreach (var docRecipient in documentRecipients.EnvelopeDocuments)
{
    foreach (var signerStatus in docRecipient.Recipients.Signers)
    {
        // docRecipient.DocumentId 为文档ID
        // signerStatus.Status 为该签署人对该文档的签署状态（如"signed"、"sent"等）
    }
}

2. 解决ListDocuments参数无效问题 #

DocuSign API的查询参数为字符串格式，而非布尔值，需确保构造ListDocumentsOptions时传入字符串类型的"true"而非bool类型的true，同时检查NuGet包版本是否为最新（旧版本可能存在参数绑定问题）。

C#代码示例：

var listDocsOptions = new ListDocumentsOptions
{
    ShowFileSize = "true" // 注意是字符串"true"
};
var documents = envelopeApi.ListDocuments(accountId, envelopeId, listDocsOptions);

若需获取文档的签署状态，可结合上述ListDocumentRecipients的结果，将文档ID与签署状态进行关联。

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