如何使用 DocuSign API 添加可编辑的空文本框（Text Tab）-php教程-PHP中文网

如何使用 DocuSign API 添加可编辑的空文本框（Text Tab）

本文详解如何通过 DocuSign REST API 在指定坐标位置添加用户可编辑的空文本框（而非预填静态值），重点说明 textTabs 的正确配置方式，包括必需字段（如 recipientId、locked）及常见误区。

本文详解如何通过 docusign rest api 在指定坐标位置添加用户可编辑的空文本框（而非预填静态值），重点说明 `texttabs` 的正确配置方式，包括必需字段（如 `recipientid`、`locked`）及常见误区。

在 DocuSign API 中，所有可交互的表单字段（包括文本框、复选框、签名域等）均通过 Tab 对象定义，并归属到特定收件人（Recipient）下。你当前代码中使用 textTabs 是完全正确的——空文本框仍属于 textTabs 数组，无需额外数组类型；关键区别在于：不设置 value 字段（或设为空字符串），并确保 locked 为 false，同时显式指定 recipientId。

✅ 正确做法如下：

$s2 = array(
    'documentId' => '3',
    'pageNumber' => '2',
    'xPosition' => '275',
    'yPosition' => '94',
    'locked'     => false,        // 必须为布尔 false（非字符串 'false'），表示用户可编辑
    'recipientId'=> '1',         // 必填！关联该 Tab 到对应收件人（需与 recipients 数组中 recipient 的 recipientId 一致）
    // 'value' => ''              // 省略 value 或设为空字符串，即呈现为空文本框
);

array_push($textTabs, $s2);

// 收件人定义中，recipientId 必须匹配上述值
$recipients[] = array(
    'roleName' => $client,
    'email'    => $email,
    'name'     => $name,
    'recipientId' => '1', // ⚠️ 注意：此字段必须存在且与 textTabs 中的 recipientId 一致
    'tabs' => array(
        'textTabs'      => $textTabs,
        'initialHereTabs' => $initials,
        'checkboxTabs'  => $checkboxes
    ),
);

? 关键注意事项：

recipientId 是强制字段：DocuSign 要求每个 Tab 必须明确归属到一个收件人，否则 API 将返回 INVALID_TAB_RECIPIENT_ID 错误；
locked 类型为布尔值：应传 false（PHP 布尔），而非字符串 'false'，避免因类型错误导致字段意外锁定；
value 字段决定是否为空：若完全省略 value，或设为 ''，则渲染为用户可输入的空白文本框；若设置了 value（如 substr($first_name, 0, -2)），则变为只读静态文本（即你当前遇到的问题）；
坐标单位为像素（基于页面左上角）：确保 xPosition/yPosition 在目标页面有效区域内，建议结合 DocuSign Web 控制台的“定位工具”校准；
文档 ID 一致性：documentId（如 '3'）必须与你上传文档时分配的 ID 完全匹配。