简短回答：用 htmlDefinition，而不是 documentBase64

要通过 DocuSign eSignature REST API 创建响应式 HTML 文档，在 Envelopes:create 请求的 documents 数组中定义文档：使用 htmlDefinition 对象，其 source 属性以纯文本（而非 Base64 字符串）承载你页面的 HTML。将 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 库默认关闭；管理员须在 Signing Settings 中开启
高级：直接发送 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"在 HTML 文档中设置 tab"指南给出了两种方法。第一种是 HTML 块：每种 tab 类型都有对应的 DocuSign HTML 标签，通过 data-ds-role、data-ds-recipient-id、required、readonly、font-size、color 等属性配置；属性值会覆盖 tab 的默认设置。第二种是 JSON 标记：在 HTML 源码中嵌入包含 tabLabel 的标记，每个标记会被 API 请求中匹配的 tab 定义替换。单选（radio）tab 是特例——其标记必须包含映射到某个 radio 组的 groupName 和 value 属性。

同一份指南中还有两个约束，漏掉就会踩坑。只有内联样式会反映到处理后的文档中；定义在页面之外的样式，如