PHP cURL调用电子签名API遇415错误：多表单数据请求排查

Here are actionable steps to resolve your 415 Unsupported Media Type error when sending multipart/form-data requests to the e-signature API:

1. Use Postman's Working Code as a Reference #

Since Postman desktop works flawlessly, leverage its code generator to get a valid PHP cURL snippet:

• Open your working Postman request.
• Click the Code button (right sidebar).
• Select PHP - cURL from the dropdown.
• Compare this code line-by-line with your own. Focus on:
  • How the file is attached (Postman uses CURLFile correctly).
  • The structure of POST fields.
  • Which headers are included (and which are omitted).

2. Stop Manually Setting the Content-Type Header #

A frequent mistake is forcing Content-Type: application/json or even multipart/form-data explicitly. When passing an array to CURLOPT_POSTFIELDS, cURL automatically generates the correct multipart/form-data header with a unique boundary string. Manually setting this header breaks boundary matching, leading to 415 errors.

3. Fix Your CURLFile Implementation #

Ensure you’re using CURLFile (the old @ file prefix is deprecated in PHP 5.5+):

// Correct implementation
$filePath = realpath('/path/to/your/document.pdf');
$file = new CURLFile($filePath, 'application/pdf', 'contract.pdf');

// Avoid these deprecated/wrong approaches
// $file = '@/path/to/document.pdf';
// $file = fopen('/path/to/document.pdf', 'r');

Also verify:

• The file path is valid (use realpath() to resolve relative paths).
• The file is readable with is_readable($filePath).

4. Structure POST Data Correctly #

The JSON payload must be a regular form field, not a separate raw body. For example, if the API expects document for the PDF and metadata for JSON:

$jsonPayload = json_encode([
    'signer_email' => 'user@example.com',
    'document_title' => 'Client Contract'
]);

$postData = [
    'document' => $file,
    'metadata' => $jsonPayload
];

Double-check field names against Postman’s request—even a small typo can cause the API to reject the request.

5. Debug with cURL Verbose Mode #

Enable verbose logging to see exactly what’s sent to the API. Add these lines to your code:

curl_setopt($ch, CURLOPT_VERBOSE, true);
$verboseLog = fopen('php://temp', 'w+');
curl_setopt($ch, CURLOPT_STDERR, $verboseLog);

// After executing the request
rewind($verboseLog);
echo stream_get_contents($verboseLog);

Compare the output to Postman’s raw request (found in Postman’s Console). Look for:

• Mismatched boundary strings in the Content-Type header.
• Missing or incorrectly formatted form fields.
• Invalid file MIME types.

6. Validate JSON Payload #

Ensure your JSON is properly encoded with json_encode()—no syntax errors or unescaped characters. Validate it with:

$json = json_encode($yourData);
if (json_last_error() !== JSON_ERROR_NONE) {
    die('Invalid JSON: ' . json_last_error_msg());
}

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