如何通过DocuSign API创建含新文档的信封？求请求体示例

没问题，我刚好做过类似的需求，直接给你具体的请求体格式和代码示例，一步到位：

你提到的POST地址是对的：https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes
请求头必须包含以下内容：

• Authorization: Bearer {your_access_token}
• Content-Type: application/json

核心是documents数组，每个文档需要传入Base64编码的文件内容，同时配合收件人、签名标签等信息。下面是完整的请求体示例：

{
  "emailSubject": "请签署这份合同文档",
  "emailBlurb": "这是需要你签署的正式合同，请完成签署后提交",
  "status": "sent", // 设置为sent会直接发送给收件人，设为draft则保存为草稿
  "documents": [
    {
      "documentId": "1", // 文档唯一标识，后续签名标签需要关联这个ID
      "name": "合作合同.pdf",
      "documentBase64": "JVBERi0xLjMKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyIC9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nE2NuwoCQQxF+/m...", // 替换为你的文件Base64编码字符串（不要带前缀）
      "fileExtension": "pdf" // 可选，但建议明确指定，避免自动推断出错
    }
  ],
  "recipients": {
    "signers": [
      {
        "email": "signer_demo@example.com",
        "name": "张小明",
        "recipientId": "1",
        "tabs": {
          "signHereTabs": [
            {
              "documentId": "1", // 和上面的documentId对应
              "pageNumber": "1",
              "xPosition": "150",
              "yPosition": "250"
            }
          ]
        }
      }
    ]
  }
}

重要提示：documentBase64必须是文件原始二进制内容经过Base64编码后的纯字符串，不要包含data:application/pdf;base64,这类前缀。

Curl 快速测试示例 #

curl --location --request POST 'https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes' \
--header 'Authorization: Bearer {your_access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "emailSubject": "请签署这份合同文档",
  "emailBlurb": "这是需要你签署的正式合同，请完成签署后提交",
  "status": "sent",
  "documents": [
    {
      "documentId": "1",
      "name": "合作合同.pdf",
      "documentBase64": "JVBERi0xLjMKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyIC9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nE2NuwoCQQxF+/m...",
      "fileExtension": "pdf"
    }
  ],
  "recipients": {
    "signers": [
      {
        "email": "signer_demo@example.com",
        "name": "张小明",
        "recipientId": "1",
        "tabs": {
          "signHereTabs": [
            {
              "documentId": "1",
              "pageNumber": "1",
              "xPosition": "150",
              "yPosition": "250"
            }
          ]
        }
      }
    ]
  }
}'

Python 实用代码示例（使用requests库） #

import requests
import base64

# 读取本地文件并转换为Base64编码
with open("合作合同.pdf", "rb") as file:
    document_base64 = base64.b64encode(file.read()).decode("utf-8")

# 配置请求参数
api_url = "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes"
request_headers = {
    "Authorization": "Bearer {your_access_token}",
    "Content-Type": "application/json"
}

request_payload = {
    "emailSubject": "请签署这份合同文档",
    "emailBlurb": "这是需要你签署的正式合同，请完成签署后提交",
    "status": "sent",
    "documents": [
        {
            "documentId": "1",
            "name": "合作合同.pdf",
            "documentBase64": document_base64,
            "fileExtension": "pdf"
        }
    ],
    "recipients": {
        "signers": [
            {
                "email": "signer_demo@example.com",
                "name": "张小明",
                "recipientId": "1",
                "tabs": {
                    "signHereTabs": [
                        {
                            "documentId": "1",
                            "pageNumber": "1",
                            "xPosition": "150",
                            "yPosition": "250"
                        }
                    ]
                }
            }
        ]
    }
}

# 发送请求并打印响应
response = requests.post(api_url, json=request_payload, headers=request_headers)
print("请求状态码：", response.status_code)
print("响应内容：", response.json())

• 务必替换{accountId}和{your_access_token}为你自己的账号ID和授权令牌
• 如果需要添加多个文档，在documents数组中新增对象即可，每个文档的documentId要保持唯一
• 签名标签的x/y坐标需要根据你的文档实际布局调整，也可以使用anchorString（锚定文本）来自动定位，比固定坐标更灵活
• 如果测试时不想立即发送给收件人，可以把status改为draft，后续在DocuSign控制台编辑并发送

内容的提问来源于stack exchange，提问作者Zoltán