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 團隊。
