DocuSign C# REST API：向现有信封添加带签署人的文档失败

嘿，我来帮你捋清楚这个问题——你之所以能成功添加文档但新签署人没被加入，核心原因是用错了DocuSign的接口端点：你当前调用的/envelopes/{envelopeId}/documents接口，专门负责处理文档的添加/更新，它会直接忽略请求体里的recipients字段，所以新签署人的信息根本没被处理。

为什么会这样？ #

DocuSign的REST API是按功能拆分端点的：

• /documents端点只关注文档操作，不管收件人
• /recipients端点才是专门用来添加、修改或删除签署人的地方

正确的操作步骤有两种方式可选： #

方式1：分两步操作（更直观，适合新手） #

1. 先添加新文档：保留你现有的/documents接口调用，但把请求体里的recipients部分删掉，只保留文档相关内容：

   url = "https://demo.docusign.net/restapi/v2/accounts/" + accountID + "/envelopes/" + envelopID + "/documents";
   strAttDOCScript = "{ \"status\": \"sent\", \"documents\": [{ \"documentId\": \"" + iDocumentID +"\", \"name\": \"" + strDocumentName +"\", \"documentBase64\": \"" + System.Convert.ToBase64String(AttFile) +"\" }] }";
   

2. 再添加新签署人：调用/recipients接口（POST方法），单独提交签署人信息：

   url = "https://demo.docusign.net/restapi/v2/accounts/" + accountID + "/envelopes/" + envelopID + "/recipients";
   strRecipientScript = "{ \"signers\": [{ \"email\": \"tuanppal@gmail.com\", \"name\": \"Sara Mason\", \"recipientId\": \"3\", \"tabs\": { \"checkboxTabs\": [{ \"tabLabel\": \"sampleCheckbox\", \"xPosition\": \"20\", \"yPosition\": \"20\", \"documentId\": \"2\", \"pageNumber\": \"1\" }], \"signHereTabs\": [{ \"conditionalParentLabel\": \"sampleCheckbox\", \"conditionalParentValue\": \"On\", \"xPosition\": \"80\", \"yPosition\": \"40\", \"documentId\": \"2\", \"pageNumber\": \"1\" }] } }] }";
   

   小提示：如果信封还处于草稿状态，你可以保持status为created，等所有内容都调整好再改为sent发送。

方式2：用信封更新接口一次性搞定（更高效） #

调用/envelopes/{envelopeId}的PUT接口，在请求体里同时包含documents和recipients字段，这样能一次完成文档添加和签署人新增：

url = "https://demo.docusign.net/restapi/v2/accounts/" + accountID + "/envelopes/" + envelopID;
strUpdateScript = "{ \"status\": \"sent\", \"documents\": [{ \"documentId\": \"" + iDocumentID +"\", \"name\": \"" + strDocumentName +"\", \"documentBase64\": \"" + System.Convert.ToBase64String(AttFile) +"\" }], \"recipients\": { \"signers\": [{ \"email\": \"tuanppal@gmail.com\", \"name\": \"Sara Mason\", \"recipientId\": \"3\", \"tabs\": { \"checkboxTabs\": [{ \"tabLabel\": \"sampleCheckbox\", \"xPosition\": \"20\", \"yPosition\": \"20\", \"documentId\": \"2\", \"pageNumber\": \"1\" }], \"signHereTabs\": [{ \"conditionalParentLabel\": \"sampleCheckbox\", \"conditionalParentValue\": \"On\", \"xPosition\": \"80\", \"yPosition\": \"40\", \"documentId\": \"2\", \"pageNumber\": \"1\" }] } }] } }";

注意：PUT请求会覆盖信封中指定的字段，如果你想保留原来的两位签署人，一定要把他们的信息也加到recipients.signers数组里，不然原有签署人会被替换掉！

额外要注意的点 #

• 确保你的API账号有修改信封收件人的权限
• recipientId必须是唯一的，你用3没问题，因为之前已经有两位签署人
• 如果信封已经发送（status为sent），修改收件人可能需要额外的操作权限，建议在草稿状态完成所有调整后再发送

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