PHP curl调用DocuSign API创建信封时如何为PDF添加签名字段

你当前的代码已经完成了信封创建、文档上传、收件人配置的基础逻辑，要添加签名字段只需要在对应签名人的配置块中新增tabs节点挂载字段配置即可，不需要修改原有文档、信封基础信息的逻辑。

核心实现逻辑 #

• DocuSign的所有交互字段（签名位、文本输入、日期填充等）都属于绑定到指定收件人的tab对象，通过信封创建接口的请求体直接提交，即可在信封生成时自动把字段挂载到对应PDF的指定位置，不需要提前编辑PDF。
• 你当前代码中开启的transformPdfFields: true作用是自动把PDF原生的AcroForm表单字段转换为DocuSign可填充字段，这个配置和手动添加的自定义tab互不冲突，可以保留。

改造后的完整可运行代码 #

$headers = array(   
     'Content-Type: application/json',
    'Authorization: Bearer '.$access_token->access_token
    );

$content_bytes = file_get_contents($_SERVER['DOCUMENT_ROOT'] .'/public/demo_documents/'.$docfile);
$doc3_b64 = base64_encode($content_bytes);

$document = array (
  'documents' => 
  array (
    0 => 
    array (
      'documentBase64' => $doc3_b64,
      'documentId' => 1,
      'fileExtension' => 'pdf',      
      'name' => 'test '.$data['signer_name'],
      "transformPdfFields"=> true
    ),
  ),
  'emailSubject' => 'Test '.$data['signer_name'],
  'recipients' => 
  array (
    'signers' => 
    array (
      0 => 
      array (
        'email' => $data['signer_email'],
        'name' => $data['signer_name'],
        'recipientId' => '1',
        // 新增签名字段配置块
        'tabs' => [
            // 手写签名位
            'signHereTabs' => [
                [
                    'documentId' => '1', // 和上传文档的documentId匹配
                    'pageNumber' => '1', // 字段所在页码
                    'xPosition' => '150', // 距离页面左侧的距离，单位为磅
                    'yPosition' => '600', // 距离页面顶部的距离，单位为磅
                    'recipientId' => '1' // 和当前签名人ID保持一致
                ]
            ],
            // 自动填充签署人姓名字段
            'fullNameTabs' => [
                [
                    'documentId' => '1',
                    'pageNumber' => '1',
                    'xPosition' => '150',
                    'yPosition' => '560',
                    'recipientId' => '1'
                ]
            ],
            // 自动填充签署日期字段
            'dateSignedTabs' => [
                [
                    'documentId' => '1',
                    'pageNumber' => '1',
                    'xPosition' => '150',
                    'yPosition' => '520',
                    'recipientId' => '1'
                ]
            ]
        ]
      ),
    ),

  ),
  'status' => 'sent',
  
);
$url = "https://demo.docusign.net/restapi/v2.1/accounts/$account_id/envelopes";

// 补充cURL初始化及收尾配置
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,json_encode($document));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// 本地开发环境可加ssl配置避免证书报错，生产环境建议开启证书校验
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
$envelopes = json_decode(curl_exec($ch));
curl_close($ch);

字段配置实用说明 #

• 坐标参考：DocuSign页面坐标原点为页面左上角，1磅=1/72英寸，常规A4PDF的页面宽度为595磅、高度为842磅，按这个范围调整x、y值就不会出现字段超出页面的问题。
• 锚点定位替代手动算坐标：如果不想手动计算坐标，可以把tab的定位方式改成锚点匹配，只要PDF文档里有你提前预埋的标记文字，就可以自动把字段放到对应位置，示例配置：

锚点定位配置参考

'signHereTabs' => [
    [
        'documentId' => '1',
        'anchorString' => '（请在此处签名）', // 匹配PDF中的固定标记文字
        'anchorXOffset' => '10', // 相对锚点文字的横向偏移
        'anchorYOffset' => '-15', // 相对锚点文字的纵向偏移
        'recipientId' => '1'
    ]
]

• 常用tab类型说明：
  • signHereTabs：手写签名位置，签署人可以直接在该位置手签、用预设签名生成
  • fullNameTabs：自动填充签署人姓名，不需要手动输入
  • dateSignedTabs：自动填充签署时的系统日期，不需要手动选择
  • textTabs：自定义文本输入框，可设置默认值、是否必填、输入长度限制

常见问题排查 #

• 提交接口后如果报字段定位错误，优先检查documentId是否和上传的文档ID完全一致，页码是否超出PDF总页数，坐标是否在页面范围内。
• 如果开启transformPdfFields后PDF原生字段重复，不需要删除原有tab配置，直接把transformPdfFields设为false即可关闭自动转换，只保留你手动配置的签名字段。
• 可以把接口返回的$envelopes对象打印出来，查看recipients.signers.tabs节点的内容，确认所有字段都被DocuSign正确接收。

内容的提问来源于stack exchange，提问作者Mahmood Rehman