2026年8月19日
DocuSign eSignature REST API 可以通过一个端点 GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/combined 返回已完成信封的签署文档及其完成证书（Certificate of Completion, CoC），并合并为单个 PDF。由于该调用的查询参数 certificate=true 是默认行为，CoC 会自动追加到合并 PDF 末尾。如果设置 certificate=false，API 会移除证书并仅返回签署文档。标准归档流程无需手动合并 PDF。
如果你需要单独获取证书，可调用 GET .../documents/certificate 仅下载 CoC，或调用 GET .../documents/archive 获取 ZIP 文件（包含每份信封文档的独立 PDF 及证书）。本指南后续将逐一介绍各选项、控制返回内容的参数，以及大多数团队在构建合规归档时容易踩坑的地方。
DocuSign 返回信封文档的三种方式
这三种获取模式使用同一个端点 GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}，区别在于传入 {documentId} 的特殊值不同。在编写代码前，用下表选择合适的选项：
表中每一行都有两个前置条件。首先，信封必须已达到 completed 状态——只要还有任何收件人未完成，CoC 就不存在，对进行中的信封调用证书端点会失败。其次，你需要使用 OAuth access token 进行身份验证，并使用分配给你账户的基础 URI（例如演示环境或生产区域数据中心），该 URI 应从 OAuth userinfo 调用中动态获取，而非硬编码。
获取包含完成证书的合并 PDF
这是大多数团队需要的模式：一次 HTTP 调用、一个 PDF 文件、自带证书。最简 curl 请求如下：
```bash
curl --request GET \
"{BASE_URL}/v2.1/accounts/{ACCOUNT_ID}/envelopes/{ENVELOPE_ID}/documents/combined" \
--header "Authorization: Bearer {ACCESS_TOKEN}" \
--output envelope_combined.pdf
```
等效的 Python 代码（使用 requests）：
```python
import requests
url = f"{base_url}/v2.1/accounts/{account_id}/envelopes/{envelope_id}/documents/combined"
headers = {"Authorization": f"Bearer {access_token}"}
response = requests.get(url, headers=headers)
response.raise_for_status()
with open("envelope_combined.pdf", "wb") as f:
f.write(response.content)
```
由于 certificate=true 是默认值，你保存的文件已经包含签署文档及随后的 CoC 页面。如需排除证书，显式添加查询字符串：
```
GET .../documents/combined?certificate=false
```
保存响应体之前，请检查 Content-Type 响应头是否为 application/pdf。出错时 DocuSign 返回的是 JSON 错误对象而非二进制数据，将 JSON 写入 .pdf 文件会产生损坏的归档文件，并在后续流程中静默失败。此外还应确认 response.status_code == 200 且响应体以 %PDF 开头，作为简易完整性校验。
单独获取完成证书
部分合规工作流将 CoC 作为独立证据文件存储，与签署合同并存但分离。此时只需更换 document ID：
```
GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/certificate
```
证书是生成的 PDF，记录了信封事件：文档发送给谁、每位收件人何时查看和签署、使用的认证方式、IP 地址和时间戳。正是这些事件历史使证书具备审计追踪功能——如果你想深入了解 CoC 各字段的含义及其作为证据的有效性，请参阅我们的 DocuSign 完成证书与审计追踪指南。
获取证书时（无论是单独获取还是包含在合并 PDF 中），你可以通过 language 查询参数控制其显示语言，可使用 en 或 zh_CN 等值。这对于跨境信封尤为重要，当监管机构或交易对手要求证据文件使用特定语言时。
此处也值得说明 archive 选项。它返回一个 ZIP 文件，其中每份信封文档都是独立的 PDF，CoC 作为单独文件包含在内。当你的文档管理系统需要单独索引证据，或单份文档较大导致合并 PDF 不便管理时，应选择 archive 而非 combined。
归档已签署信封时的常见陷阱
在完成前请求。 最常见的错误是在信封仍处于 sent 或 delivered 状态时就轮询证书。应在确认信封状态后再触发获取调用，更好的做法是订阅 DocuConnect webhooks，当收到 envelope-completed 事件时再触发下载。Webhooks 完全消除了轮询循环，实现近实时归档。
假设证书始终附加。 复制了包含 certificate=false 的代码片段，或在 combined 和 archive 之间切换时未做检查，最终导致归档 PDF 缺少证据页。即使在需要默认行为时，也应在代码中显式声明该参数，确保意图在后续重构中得以保留。
信任文件扩展名而非实际载荷。 错误响应以 JSON 形式返回。在持久化到长期存储前，务必验证 Content-Type 响应头和 %PDF 魔术字节。
忽略下游篡改证据。 合并 PDF 只有在下载后保持完整才能作为有效证据。在接收时对文件计算哈希值（SHA-256）并将哈希与归档元数据一同存储。如果你不确定签署 PDF 具备哪些保护措施以及签署后是否可能被修改，请阅读签署后的文档能否被修改一文，它解释了签名验证如何检测签署后的变更。当你之后需要证明文件未被改动时，了解如何在 PDF 中验证签名则能形成闭环。
丢失信封与归档的映射关系。 将 envelopeId、账户 ID、获取时间戳和你使用的确切端点变体与文件一起存储。六个月后审计时，这些元数据决定了你是能在五分钟内查到结果，还是需要进行取证级重建。
合规归档实施清单
将 DocuSign 文档获取接入生产流水线时，使用此清单：
- [ ] 使用 OAuth 身份验证并动态解析账户基础 URI
- [ ] 通过 Connect
envelope-completedwebhook 触发获取，而非定时器 - [ ] 调用文档端点前验证信封
status等于completed - [ ] 调用
GET .../documents/combined时显式声明certificate=true（或根据你的记录系统需求使用archive） - [ ] 保存前断言
Content-Type: application/pdf（或application/zip）且状态码为 200 - [ ] 当证书需要以非默认语言渲染时设置
language参数 - [ ] 在接收时计算并存储归档文件的 SHA-256 哈希值
- [ ] 将信封元数据（信封 ID、时间戳、端点变体）与文件一同持久化
- [ ] 对归档存储应用保留策略和访问控制
- [ ] 每季度随机抽取一个已归档信封进行获取演练，证明归档可读
如果你的团队正在评估此工作流的成本侧——信封量级、API 方案层级以及获取方式如何匹配你的协议——我们对 DocuSign 成本的分析涵盖了影响重度 API 集成的定价维度。
规模化自动归档签署文档：Nota Sign
如果你正在构建这套获取与归档流水线，是因为你的组织需要跨边境大规模签署，那么值得思考：这个流水线本身是否应该交给别人来维护。Nota Sign 是法大大（FaDaDa）的全球电子签名平台——法大大已连续多年被 IDC 评为中国电子签名软件市场第一名——其法律效力覆盖 100 多个国家和地区，并提供深度的亚太区合规支持，包括 iAM Smart、Singpass、SES/AES/QES 签名级别及区域数据中心。已完成信封、证书和审计证据均可通过平台的电子签名产品直接获取和归档，无需你自行维护 webhook 消费者和 PDF 校验器。
在商业条款方面，Nota Sign 不收取 per-seat 费用，这对小团队非常友好；中型市场和大型企业客户则可根据自身量和合规需求定制方案。如果你想了解获取、归档和跨境合规的实际运作方式，请联系 Nota Sign 团队。
