如何解决PHP+CURL调用Freshdesk API上传DataURL附件报错问题？

问题场景 #

使用PHP+CURL调用Freshdesk V2 API创建带画布截图（DataURL格式）的工单时，触发附件格式不匹配错误，移除attachments字段后请求正常。

错误信息 #

{
 "field": "attachments", 
 "message": "It should contain elements of type valid file format only", 
 "code": "datatype_mismatch" 
}

问题原因 #

1. Freshdesk V2 API不支持在application/json格式的请求体中直接传入DataURL格式的附件
2. 带附件的工单创建请求必须使用multipart/form-data格式提交
3. DataURL包含data:image/png;base64,前缀，需要提取纯base64编码的文件内容并转换为二进制文件

修正方案 #

步骤1：处理DataURL，提取并转换为二进制文件内容 #

// 拆分DataURL，提取纯base64编码部分
list($type, $dataUrlContent) = explode(';', $dataUrl);
list(, $base64Content) = explode(',', $dataUrlContent);
// 转换为二进制文件内容
$fileBinary = base64_decode($base64Content);

步骤2：构造multipart/form-data格式的请求 #

使用PHP的CURLFile类处理附件，CURL会自动生成正确的multipart/form-data请求头及边界：

// 创建临时文件存储截图内容
$tmpFile = tempnam(sys_get_temp_dir(), 'fd_screenshot');
file_put_contents($tmpFile, $fileBinary);

// 构造请求参数
$postParams = [
    'description' => $messageBody,
    'subject' => 'Bug Report from Client',
    'email' => $replyTo,
    'priority' => 1,
    'status' => 2,
    // 使用CURLFile指定附件，文件名需带后缀以识别格式
    'attachments[]' => new CURLFile($tmpFile, 'image/png', 'Screenshot.png')
];

// 初始化CURL
$url = "https://domain.freshdesk.com/api/v2/tickets";
$apiKey = "your_api_key_here";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postParams);
// 禁止手动设置Content-Type，让CURL自动处理multipart格式
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $apiKey);

// 执行请求
$resultStr = curl_exec($ch);

// 清理临时文件
unlink($tmpFile);

关键注意事项 #

• 必须使用CURLFile类，不能直接在JSON中传入base64或DataURL
• 文件名需包含正确的后缀（如.png），Freshdesk依赖此识别文件类型
• 不要手动设置Content-Type: application/json，否则会破坏multipart格式
• 临时文件使用后需及时删除，避免服务器存储冗余

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