PHP中使用cURL调用DocuSign API创建信封返回Null，请求排查代码问题

问题描述 #

尝试通过PHP结合cURL调用DocuSign v2.1 API创建信封，执行后返回Null，无法完成信封创建操作。

原代码 #

<?php
$realpath = "uploads/";
$doc_file = 'dummy.pdf';
$content_bytes = file_get_contents($realpath . $doc_file);
$base64_file_content = base64_encode($content_bytes);

$certificate_location = 'C:\\wamp64\\bin\\php\\php7.4.26\\extras\\ssl\\cacert.pem';

$ch = curl_init();

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, $certificate_location);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, $certificate_location);

curl_setopt($ch, CURLOPT_URL, 'https://demo.docusign.net/v2.1/accounts/2c5281fc-8adb-4bb1-a764-0a77bd98ec0e/envelopes');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
  \"documents\": [
    {
      \"documentBase64\": $base64_file_content,
      \"documentId\": 15464655,
      \"fileExtension\": \"pdf\",
      \"name\": \"document12345\"
    }
  ],
  \"emailSubject\": \"Simple Signing Example\",
  \"recipients\": {
    \"signers\": [
      {
        \"email\": \"sandeep0822@gmail.com\",
        \"name\": \"Sandeep\",
        \"recipientId\": \"{{recipientId}}\"
      }
    ]
  },
  \"status\": \"sent\"
}");

$headers = array();
$headers[] = 'Content-Type: application/json';
$headers[] = 'Authorization: Bearer eyJ0eXAiOiJNVCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiNjgxODVmZjEtNGU1MS00Y2U5LWFmMWMtNjg5ODEyMjAzMzE3In0.AQoAAAABAAUABwCAxDrMAUfbSAgAgARe2kRH20gCAPvG8RYXzvVIl65odwsvffsVAAEAAAAYAAgAAAAxAAAAMgAAACsAAAA4AAAALQAAAC8AAAA1AAAAMwAAAA0AJAAAAGFhOWZhNjgzLWY0YjQtNGE3Mi05NWE3LTNiNDM0NjczYTVhMyIAJAAAAGFhOWZhNjgzLWY0YjQtNGE3Mi05NWE3LTNiNDM0NjczYTVhMzAAgEXPZP5G20g3ANtSvxlqLSpBqqxieM2bkLM.PyRvZdPTQTrVD5aSKZ0hrRmB9x3ZQ6CeCz5GwcEGLe60qN4XOeE7NT8a83NnHldTIcXBJIosI2WiohFz1L8uyth6Ea38Vk4oAni0gnTXHUKSRyERa7R-gEDNoNdIHpdth7iMQXLMDUPcCY03o0xQV3AP3Oov1Pk770rTBi5XRkrsqpKqLd1HqlrKPF6ahhxai00R1-d0q0ITrwIHzXNdGdd5s7PWpuhYNQUgdHpb5rwqPE51PX48KBBB2g-xGa16ngqUC7EchgtbtGkZBzHKNmiGQ9kufWLi74WlLFgidxh1jxaBOZsm1MT723PbV-1ABOtecZYuU9Eurqp1K5PxLQ';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
$response = json_decode($result);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
echo '<pre>';
var_dump($response);
echo '</pre>';
curl_close($ch);
?>

问题点及修复方案 #

• SSL验证参数设置错误
  CURLOPT_SSL_VERIFYHOST的有效值是2（用于验证主机名），CURLOPT_SSL_VERIFYPEER是布尔值（true/false），证书路径需要通过CURLOPT_CAINFO指定。原代码把两个参数都设为证书路径，导致SSL验证失败，curl_exec返回false，json_decode后得到Null。
  修复代码：

  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  curl_setopt($ch, CURLOPT_CAINFO, $certificate_location);
  

• JSON字符串拼接错误
  $base64_file_content直接拼入JSON字符串但未加双引号，导致JSON格式无效。base64内容属于字符串类型，必须被双引号包裹才能符合JSON语法规范。
  修复方式：手动拼接时给变量加转义双引号，或更稳妥地用json_encode生成POST数据：

  $postData = [
      'documents' => [
          [
              'documentBase64' => $base64_file_content,
              'documentId' => 15464655,
              'fileExtension' => 'pdf',
              'name' => 'document12345'
          ]
      ],
      'emailSubject' => 'Simple Signing Example',
      'recipients' => [
          'signers' => [
              [
                  'email' => 'sandeep0822@gmail.com',
                  'name' => 'Sandeep',
                  'recipientId' => '1'
              ]
          ]
      ],
      'status' => 'sent'
  ];
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($postData));
  

• RecipientId使用无效占位符
  recipientId必须是具体的字符串或数字（如"1"），DocuSign要求该值为收件人的唯一标识符，不能使用{{recipientId}}这类模板占位符（除非是基于模板创建信封的场景）。

• 错误处理逻辑不完善
  原代码先执行json_decode再检查curl错误，若curl_exec返回false，json_decode(false)会得到Null。应先判断$result是否为false，再进行后续处理：

  $result = curl_exec($ch);
  if (curl_errno($ch)) {
      echo 'Error:' . curl_error($ch);
      curl_close($ch);
      exit;
  }
  $response = json_decode($result);
  if (json_last_error() !== JSON_ERROR_NONE) {
      echo 'JSON解析错误:' . json_last_error_msg();
  }
  echo '<pre>';
  var_dump($response);
  echo '</pre>';
  curl_close($ch);
  

内容的提问来源于stack exchange，提问作者Rest API