如何使用 C# DocuSign 的 API 查看一批信封的自定义字段

How can I view a batch of Envelopes' custom fields using C# DocuSign's API

这是一个关于使用 DocuSign API 及其 C# SDK 将文档发送给收件人进行数字签名,然后在收件人级别跟踪状态更改的问题。我在将状态更改与各个收件人相关联时遇到问题。

每个信封有一个收件人。我使用 BulkEnvelopesAPI CreateBulkListRequest 方法发送一批。然后,我使用 EnvelopesAPI ListStatusChanges 方法获取状态更改。我可以在发送新文件时看到它们,在文件签名后我可以看到状态变化。

但是,我无法将这些状态更改与我的收件人联系起来。所以我在信封中添加了一个自定义字段来为收件人保留一个唯一值。 ListStatusChanges 响应包含一个信封列表,每个信封都包含一个 CustomField 属性,但它始终为空。我可以使用 EnvelopesAPI ListCustomFields 方法,使用来自 ListStatusChanges 的信封 ID 单独获取信封,但这将意味着大量 API 调用。我将以 1000 份为一批发送大约 4000 份文件。如果我必须逐个检查信封,我往往会达到每小时 1000 份 API 呼叫限制。

所以我的问题是:如何在信封上设置自定义字段,以便我可以在 ListStatusChanges 响应信封的自定义字段 属性 中看到它,而不必调用 API依次为每个信封?

以下是一些可能有用的代码摘录:

当我创建 BulkSendList 时,我在其信封中创建了占位符:

          var theEnvelopeDefinition = new EnvelopeDefinition
            {
                TemplateId = myConfiguration["TemplateId"],
                EnvelopeIdStamping = "false",
                EmailSubject = myConfiguration["EmailSubject"],
                Status = "created",
                CustomFields = new CustomFields
                {
                    TextCustomFields =
                        new List<TextCustomField>
                        {
                            new() { Name = "FRN" }
                        }
                }
            };
:
:
:
        myEnvelopeApi.CreateEnvelope(myAccountId, theEnvelopeDefinition);

当我将收件人添加到批量发送列表时,我会这样做:

           var theBulkSendingList = new BulkSendingList
            {
                BulkCopies = new List<BulkSendingCopy>(),
                Name = "Adviser Terms of Business Mailing"
            };
            foreach (ZurichAdvisersDocuSignControl aWorkItem in myWorkItems)
            {
                var theBulkSendingCopy = new BulkSendingCopy
                {
                    CustomFields = new List<BulkSendingCopyCustomField>
                    {
                        new() { Name = "FRN", Value = aWorkItem.FcaRegistrationNumber },
                        new() { Name = "EmailAddress", Value = aWorkItem.EmailAddress }
                    },
                    EmailSubject = "This is a test email",
                    Recipients = new List<BulkSendingCopyRecipient>
                    {
                        new()
                        {
                            Name =
                                $"{aWorkItem.RecipientFirstName} {aWorkItem.RecipientLastName}",
                            Email = aWorkItem.EmailAddress,
                            RecipientId =
                                "1" // this has to match the envelope and possibly also something in the template
                        }
                    },
                    EmailBlurb =
                        string.Format(
                            CultureInfo.InvariantCulture,
                            theEmailBlurb,
                            theGreeting,
                            aWorkItem.RecipientFirstName)
                };

                theBulkSendingList.BulkCopies.Add(theBulkSendingCopy);
            }

            BulkSendingList theBulkSendList =
                myBulkEnvelopesApi.CreateBulkSendList(myAccountId, theBulkSendingList);
            myBulkListId = theBulkSendList.ListId;

当我请求状态更改时,我会这样做:

            var theEnvelopeApi = new EnvelopesApi(myApiClient);
            var theOptions = new EnvelopesApi.ListStatusChangesOptions
            {
                fromDate = DateTime.Now
                   .AddDays(-1)
                   .ToString("yyyy/MM/dd")
            };

            // Call the API method:
            EnvelopesInformation theResults =
                theEnvelopeApi.ListStatusChanges(myAccountId, theOptions);

在最后一步的结果中,我得到了一个信封列表,其中包括 BulkSendList 发送的信封。它们都有一个空的 CustomFields 属性。他们确实有一个 CustomFieldsUri 属性,如果我在 Postman 中使用它,它会显示我在 CreateBulkSendList 中设置的 CustomField 值。或者我可以一次调用一个信封的 ListCustomField。但无论哪种方式都会导致太多 API 调用。

有什么想法吗?有没有更好的方法来做我想做的事情?我可以硬着头皮实施一些管理每小时 1000 API 呼叫限制的东西,但是 BulkSendLists 的存在给了我希望,我不需要这样做。或者我可以过滤 ListStatusChanges 调用以仅显示自上次检查以来状态已超过已发送的信封;这将减少返回的更改数量,从而减少我每小时需要执行的 ListCustomFields 调用数量,但仍然存在达到限制的风险。

谢谢

史蒂夫

https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/ 看到这个:

您的 C# 代码应更改为:

        var theOptions = new EnvelopesApi.ListStatusChangesOptions
        {
            include = "custom_fields",
            fromDate = DateTime.Now.AddDays(-1).ToString("yyyy/MM/dd")
        };