本文详解如何通过 Docusign REST API 在指定坐标位置添加一个用户可编辑、初始为空的文本框（Text Tab），而非预填静态值，并指出关键参数（如 recipientId 和 locked）的必要性与正确用法。
本文详解如何通过 docusign rest api 在指定坐标位置添加一个用户可编辑、初始为空的文本框（text tab），而非预填静态值，并指出关键参数（如 `recipientid` 和 `locked`）的必要性与正确用法。
在使用 DocuSign API 动态生成签署文档时，常需为收件人预留可填写的空白字段（例如“客户姓名”“备注说明”等）。与预设静态文本不同，空文本框（editable text tab）必须显式声明其所属收件人（recipientId），并确保 locked 设为 false（或省略该字段，因默认即为 false）——最关键的是：完全不设置 value 字段。一旦设置了 value（即使为空字符串 ''），DocuSign 会将其渲染为只读静态文本，失去用户编辑能力。
以下为正确添加空文本框的 PHP 示例代码：
$s2 = array(
'documentId' => '3',
'pageNumber' => '2',
'xPosition' => '275',
'yPosition' => '94',
'recipientId' => '1', // ✅ 必填：关联到对应 recipient（如 signers[0]）
// 'value' => '', // ❌ 切勿设置 value（包括空字符串），否则变为只读
// 'locked' => false, // ✅ 可省略（默认 false），若显式设置请用布尔值而非字符串
);
array_push($textTabs, $s2);
// 注意：recipientId 必须与 recipients 数组中对应收件人的索引/ID一致
$recipients = array(
array(
'roleName' => $client,
'email' => $email,
'name' => $name,
'recipientId' => '1', // ✅ 此处 recipientId 必须与 textTabs 中的 recipientId 匹配
'tabs' => array(
'textTabs' => $textTabs,
'initialHereTabs' => $initials,
'checkboxTabs' => $checkboxes
)
)
);⚠️ 重要注意事项：
-
recipientId是强制字段：每个 tab 必须明确归属到某一位收件人，且该 ID 需与recipients数组中对应收件人的recipientId完全一致（类型为字符串）； -
value字段必须完全省略：设置'value' => ''或'value' => null均会导致字段不可编辑；仅当需要预填内容时才传入非空字符串； -
locked默认为false，无需显式设置；若手动指定，请使用 PHP 布尔值false，而非字符串'false'（后者可能被 API 解析异常）； - 坐标单位为磅（points），原点在页面左上角；建议结合 DocuSign Web 控制台的“定位工具”校准位置。
总结：创建可编辑空文本框的核心逻辑是——用 textTabs 数组承载字段定义，严格绑定 recipientId，彻底移除 value 键，并确保收件人对象中存在匹配的 recipientId。此举既满足自动化填充需求，又保留终端用户的灵活填写权限，是构建专业电子签约流程的关键实践。
