2026年8月28日
簡短答案：用 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 文件庫 | 預設關閉；須由管理員在簽署設定中啟用 |
| 進階：直接發送 HTML | htmlDefinition.source 承載你的原始 HTML | 以程式碼生成文件的範本驅動應用 | 生產方案可用性；受限制的 HTML/CSS 元素 |
| 進階 + Smart Sections | displayAnchors 包裹 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 屬性。
同一份指南中有兩項限制，漏看就會出問題。只有行內樣式會反映在處理後的文件中；在頁面之外定義的樣式，例如 </code> 區塊或外部 CSS，均不會生效。另外，透過 <code>htmlDefinition</code> 指派 tab 時，tab 的角色必須映射到一位收件人——請在簽署人上設定 <code>roleName</code>（或使用伺服器範本、複合範本），讓行內 tab 定義解析到正確的人。</p>
<p>完成後，<a href="/zh-HK/blog/docusign-api-get-tab-data-form-data-signed-doc-json-export">透過 API 從已簽署文件提取 tab 與表單數據</a>，就是你的後端記錄簽署人所填內容的方式。</p>
<h2 id="面向手機優化的-Smart-Sections">面向手機優化的 Smart Sections</h2>
<p>Smart Sections 是 <code>htmlDefinition</code> 內的手機優化層。根據響應式簽署概念指南，它們支援簽署人可展開和收合的摺疊區段、把多欄表格轉為單欄以適應窄螢幕的旋轉表格，以及在簽署人繼續前設置停頓點的 Continue 按鈕。無論是 DocuSign 從 PDF 轉換的文件，還是你直接發送的 HTML，它們都適用。</p>
<p>上面的 JSON 展示了完整結構：<code>displayAnchors</code> 項目帶有 <code>startAnchor</code>、<code>endAnchor</code>、<code>removeStartAnchor</code>、<code>removeEndAnchor</code> 和 <code>caseSensitive</code>，另加一個 <code>displaySettings</code> 物件，其 <code>display</code> 值（此處為 <code>responsive_table_single_column</code>，即旋轉表格模式）決定行為，<code>tableStyle</code> 和 <code>cellStyle</code> 則提供行內 CSS。必須提供起始錨點、結束錨點，或兩者兼有；如果錨點字串在 HTML 中找不到，該顯示錨點會被忽略——因此錨點必須是在範本渲染後仍然存活的字面、唯一字串。API 參考文件還記載了 <code>headerLabel</code>、<code>displayOrder</code>、<code>displayPageNumber</code> 和 <code>displayAnchorPrefix</code>（至少 4 個字元可提升錨點處理效能）。</p>
<h2 id="需在沙箱環境驗證的限制與陷阱">需在沙箱環境驗證的限制與陷阱</h2>
<p>請在開發者沙箱中逐項驗證以下各點，並在投入生產前向 DocuSign 支援確認與方案相關的行為。</p>
<ol>
<li><strong>帳戶啟用狀態。</strong> 基本響應式簽署預設關閉；進階選項在所有開發者帳戶可用，但僅限部分生產方案。不要因沙箱成功就假設生產環境一致。</li>
<li><strong>圖片必須內嵌。</strong> 直接發送 HTML 時不能使用圖片檔案連結；圖片必須以 Base64 編碼為 data URI 放在 <code><img></code> 標籤內，否則不會顯示。</li>
<li><strong>僅限行內樣式。</strong> 外部樣式表和 <code><style></code> 區塊不會生效；請把樣式移到每個元素的行內屬性中。</li>
<li><strong>受限制的 HTML 與 CSS。</strong> 基於安全原因，Responsive Signing 不允許使用部分 HTML 元素、屬性和 CSS 屬性。確定設計系統前，請先查閱 DocuSign 指南中的允許元素清單。</li>
<li><strong>不支援 RTL。</strong> Responsive Signing 目前不支援希伯來文、阿拉伯文、波斯文等從右至左書寫的語言。</li>
<li><strong>JSON 引號問題。</strong> 嵌入 JSON 的 HTML 中多餘的雙引號會導致反序列化錯誤；請在 HTML 定義內使用撇號。</li>
<li><strong>發送前先預覽。</strong> eSignature Admin 中的 Preview 選項可展示內容在響應式體驗中對手機簽署人的呈現效果。</li>
<li><strong>用量成本。</strong> 如果這些簽署信封會以產品級規模產生，請圍繞 <a href="/zh-HK/blog/docusign-vs-dropbox-sign-api-rate-limits-pricing-tier-review-2026">DocuSign API 速率限制與定價層級</a> 規劃容量，而非只做單一信封測試。</li>
</ol>
<h2 id="手機優先簽署-條款更簡單-Nota-Sign">手機優先簽署、條款更簡單：Nota Sign</h2>
<p>響應式 HTML 解決的是文件在手機上的呈現問題；至於背後的平台是否適合你的產品——功能按方案設限、按席位定價的模式是為銷售團隊而非以 API 大量發送的場景而設——則是另一個獨立的決定。</p>
<p>Nota Sign 是 FaDaDa 面向全球業務的電子簽名平台，其中三項優勢與手機簽署的建構直接對應：</p>
<ul>
<li><strong>隨時隨地完成簽署</strong> —— 法律覆蓋 100 多個國家和地區，背後是 FaDaDa 連續多年位列 IDC 中國電子簽名軟件市場第一的實力，身處任何市場的簽署人都能在手機上以完整法律效力完成簽署。</li>
<li><strong>內建 APAC 身份認證</strong> —— iAM Smart、Singpass 及 SES/AES/QES 保證級別，加上區域數據中心；我們的<a href="/zh-HK/blog/china-esignature-rest-api-for-software-developers">中國電子簽名 REST API 指南</a>涵蓋了本地整合模式。</li>
<li><strong>切合 API 產品的定價</strong> —— 不設按席位收費，讓小型團隊也能維持運作；中端市場和企業買家則以度身訂造的方案合作。</li>
</ul>
<p>更全面的評估，可參考<a href="/zh-HK/blog/what-is-docusign-alternatives">何時比較 DocuSign 替代方案才有意義</a>，然後<a href="/zh-HK/contact?ch=blog">與 Nota Sign 團隊展開對話</a>。</p>
