使用C#调用DocuSign Rest API创建信封时遇URL资源解析错误

问题描述 #

调用DocuSign REST API创建信封时，收到错误响应：提供的URL无法解析为资源，使用的C#代码如下：

using (var httpClient = new HttpClient())
{
    httpClient.BaseAddress = new Uri(config.Value.BaseUrl);
    httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AccessToken);

    var requestContent = new MultipartFormDataContent();

    var filePath = System.IO.Path.Combine("Sample.pdf");
    byte[] pdfBytes = System.IO.File.ReadAllBytes(filePath);
    // Add PDF document
    //byte[] pdfBytes = System.IO.File.ReadAllBytes(pdfFilePath);

    requestContent.Add(new ByteArrayContent(pdfBytes), "file", "Sample.pdf");

    // Add recipient information
    var recipient = new
    {
        email = recipientEmail,
        name = recipientName,
        recipientId = "1",
        clientUserId = "123" // Unique identifier for the recipient in your system
    };
    var recipients = new { signers = new[] { recipient } };
    requestContent.Add(new StringContent(JsonConvert.SerializeObject(recipients), Encoding.UTF8, "application/json"), "recipients");
     
    HttpResponseMessage response = await httpClient.PostAsync("envelopes", requestContent);

    if (!response.IsSuccessStatusCode)
    {
        throw new Exception($"Failed to create envelope: {response.ReasonPhrase}");
    }

    string responseContent = await response.Content.ReadAsStringAsync();
    dynamic responseData = JsonConvert.DeserializeObject(responseContent);

    return responseData.envelopeId;
}

可能的原因及解决办法 #

• BaseUrl配置不完整
  DocuSign的API要求BaseUrl必须包含完整的账户级路径，比如沙箱环境格式为https://demo.docusign.net/restapi/v2.1/accounts/{你的账户ID}，生产环境为https://www.docusign.net/restapi/v2.1/accounts/{你的账户ID}。如果config.Value.BaseUrl只到域名或/restapi层级，缺少API版本和账户ID，就会导致URL解析失败。

• 请求参数格式不符合要求
  DocuSign的multipart创建信封请求中，核心配置参数的名称必须是envelopeDefinition，而非你代码中的recipients。你当前只传递了收件人信息，缺少信封状态、文档关联等核心定义，这会导致API无法识别请求资源。需要构造包含完整信息的envelopeDefinition对象。

• 文件路径与参数匹配问题
  确保Sample.pdf存在于程序可访问的路径下，同时要在envelopeDefinition中指定对应的documentId，保证文件与配置的关联关系正确。

• 令牌有效性与权限问题
  检查AccessToken是否有效，且具备创建信封的权限。无效或权限不足的令牌可能返回误导性的URL解析错误，建议通过DocuSign的用户信息接口验证令牌状态。

修正后的完整代码示例 #

using (var httpClient = new HttpClient())
{
    // 确保BaseUrl为完整账户级路径：https://demo.docusign.net/restapi/v2.1/accounts/{你的账户ID}
    httpClient.BaseAddress = new Uri(config.Value.BaseUrl);
    httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", AccessToken);

    var requestContent = new MultipartFormDataContent();

    var filePath = System.IO.Path.Combine("Sample.pdf");
    if (!System.IO.File.Exists(filePath))
    {
        throw new FileNotFoundException("未找到指定的PDF文件", filePath);
    }
    byte[] pdfBytes = System.IO.File.ReadAllBytes(filePath);
    requestContent.Add(new ByteArrayContent(pdfBytes), "file", "Sample.pdf");

    // 构造收件人信息
    var recipient = new
    {
        email = recipientEmail,
        name = recipientName,
        recipientId = "1",
        clientUserId = "123" // 你的系统中收件人的唯一标识
    };

    // 构造完整的信封定义
    var envelopeDefinition = new
    {
        status = "sent", // 设置为"sent"立即发送，"created"则保存为草稿
        documents = new[]
        {
            new
            {
                documentId = "1", // 与添加的文件对应
                name = "Sample.pdf"
            }
        },
        recipients = new
        {
            signers = new[] { recipient }
        }
    };

    // 添加信封定义JSON，参数名必须为"envelopeDefinition"
    requestContent.Add(new StringContent(JsonConvert.SerializeObject(envelopeDefinition), Encoding.UTF8, "application/json"), "envelopeDefinition");
     
    HttpResponseMessage response = await httpClient.PostAsync("envelopes", requestContent);

    if (!response.IsSuccessStatusCode)
    {
        // 获取详细错误信息辅助排查
        string errorContent = await response.Content.ReadAsStringAsync();
        throw new Exception($"创建信封失败: {response.ReasonPhrase}，详细错误: {errorContent}");
    }

    string responseContent = await response.Content.ReadAsStringAsync();
    dynamic responseData = JsonConvert.DeserializeObject(responseContent);

    return responseData.envelopeId;
}

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