簡短答案：用 htmlDefinition，而不是 documentBase64

要透過 DocuSign eSignature REST API 建立響應式 HTML 文件，請在 Envelopes:create 請求的 documents 陣列中定義該文件，加入一個 htmlDefinition 物件，其 source 屬性以純文字形式承載你頁面的 HTML——而不是 Base64 字串。將 documentId 設為 "1" 之類的字串，設定文件 name，並將 fileExtension 設為 "html"（DocuSign 的工程部落格亦展示過使用 "htm" 的可行範例）。然後把簽署信封 POST 到 /restapi/v2.1/accounts/{accountId}/envelopes。以這種方式建立的文件會經由 DocuSign 的 Responsive Signing 系統處理，手機和平板上的簽署人會看到一個可隨螢幕縮放的網頁式簽署頁面，而非固定版面的 PDF。

要避開的陷阱是：把 HTML 位元組放進 documentBase64。DocuSign 的開發者支援團隊已明確記載，這種做法會讓文件走一般處理管線，不會產生響應式文件；在某些帳戶中更會直接回傳錯誤，指出該呼叫不允許使用 HTML。

還有一點可用性上的注意事項：進階響應式簽署——即直接發送 HTML 並使用 Smart Sections——在所有開發者（沙箱）帳戶中均可使用，但只開放給部分生產方案；而基本響應式簽署（自動把 PDF 轉為 HTML）預設是關閉的，須由帳戶管理員啟用。請先向 DocuSign 支援確認你的生產方案具備哪些能力，並先在沙箱環境驗證行為。

響應式簽署的運作方式

DocuSign 把響應式簽署分為兩個層級。在基本響應式簽署中，你提供 PDF（或其他受支援的檔案類型），由 DocuSign 轉換為可簽署的 HTML 文件；既有 tab 會被保留，錨點 tab 仍依附在其文字上，轉換結果會作為簽署信封附件儲存，可供你取回。在進階響應式簽署中，你直接發送 HTML，並可選擇加入 Smart Sections。兩者產生的頁面都會動態調整尺寸，為手機簽署帶來比固定 PDF 更好的體驗。

htmlDefinition 物件還提供 API 參考文件中的手機專屬控制項：maxScreenWidth 可將響應式 HTML 版本限制在指定像素寬度或以下的螢幕（較大螢幕會看到 PDF 版本），showMobileOptimizedToggle 則會在行動裝置上顯示「手機友善」切換開關，讓簽署人在完成前可切換至 PDF 檢視。

方案運作方式適用場景注意事項
固定版面 PDF 文件標準 documentBase64 簽署信封必須與印刷正本一致的受規管版面手機上需捏合縮放；完成率偏低
基本響應式簽署DocuSign 將你的 PDF/Word 轉為可簽署的 HTML無法改動的現有 PDF 文件庫預設關閉；須由管理員在簽署設定中啟用
進階：直接發送 HTMLhtmlDefinition.source 承載你的原始 HTML以程式碼生成文件的範本驅動應用生產方案可用性；受限制的 HTML/CSS 元素
進階 + Smart SectionsdisplayAnchors 包裹 HTML 的部分區段手機上含表格的長篇協議在 HTML 中找不到的錨點會被忽略

簽署信封請求：程式碼中的 htmlDefinition

官方建立可簽署 HTML 文件的操作指南分為三個步驟：取得 OAuth 權杖、建立包含 htmlDefinition 節點的簽署信封定義、呼叫 eSignature REST API。以下是以 curl 形式呈現的請求，憑證使用佔位符。

```bash

curl -s -X POST "https://demo.docusign.net/restapi/v2.1/accounts/{$ACCOUNT_ID}/envelopes" \

-H "Authorization: Bearer {$JWT}" \

-H "Content-Type: application/json" \

-d @envelope.json

```

下面的 envelope.json 請求體以文字形式承載 HTML，為 tab 指派映射了一個簽署人角色，並包含一個 Smart Section 定義：

```json

{

"emailSubject": "Your mobile-friendly agreement",

"status": "sent",

"documents": [

{

"documentId": "1",

"name": "agreement.html",

"fileExtension": "html",

"htmlDefinition": {

"source": "

Service Agreement

Terms text here

pricing_table_start

Plan A

pricing_table_end

",

"displayAnchors": [

{

"startAnchor": "pricing_table_start",

"endAnchor": "pricing_table_end",

"removeStartAnchor": true,

"removeEndAnchor": true,

"caseSensitive": true,

"displaySettings": {

"display": "responsive_table_single_column",

"tableStyle": "width:100%;max-width:816px;margin-left:auto;margin-right:auto;",

"cellStyle": "text-align:left;padding:0px;"

}

}

]

}

}

],

"recipients": {

"signers": [

{

"email": "signer@example.com",

"name": "Example Signer",

"recipientId": "1",

"roleName": "Signer"

}

]

}

}

```

有三個細節必須留意。第一，documentId 必須是 1 至 2,147,483,647 之間的整數，以不帶逗號的字串編碼；tab 透過它引用文件。第二，source 是純文字——操作指南明確指出，要把頁面的 HTML 直接加入 source 的值，而不是 Base64。第三，留意引號用法：DocuSign 的工程師建議在 HTML 定義內盡量少用引號、改用撇號，因為嵌入 JSON 的 HTML 中多餘的雙引號經常導致反序列化錯誤。

簽署信封建立後，簽署人會收到一封電郵，內含可在 DocuSign 手機應用程式或網站使用的簽署連結。簽署信封完成後，已簽署的文件和證據都保存在已完成的信封中——應保留哪些內容，可參閱 DocuSign 完成證書與審計追蹤紀錄指南。你亦可以用 GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/html_definitions（EnvelopeHtmlDefinitions:list）讀回已儲存的定義。

在 HTML 簽署文件中放置 tab

響應式 HTML 文件中的 tab 不使用 xPosition/yPosition 座標。DocuSign 的「Setting tabs in HTML documents」指南介紹了兩種方法。第一種是 HTML 區塊：每種 tab 類型都有對應的 DocuSign HTML 標籤，透過 data-ds-role、data-ds-recipient-id、required、readonly、font-size、color 等屬性配置；屬性值會覆寫 tab 的預設值。第二種是 JSON 標記：在 HTML 原始碼中嵌入包含 tabLabel 的標記，每個標記會被你的 API 請求中對應的 tab 定義取代。單選按鈕 tab 是特例——其標記必須包含映射到單選群組的 groupName 和 value 屬性。

同一份指南中有兩項限制，漏看就會出問題。只有行內樣式會反映在處理後的文件中；在頁面之外定義的樣式，例如