FedEx图片上传API中attachment参数传递问题求助

调用FedEx REST API的图片上传接口 /documents/v1/lhsimages/upload 时，收到以下错误：

[errors] => stdClass Object
    (
        [code] => 1001
        [message] => Invalid request: invalid input : Invalid document details
    )

常规FedEx API请求使用JSON编码的请求体通过CURLOPT_POSTFIELDS传递，这种方式在其他接口可行，但该图片上传接口需要同时传递字段数据和文件，官方参数示例如下：

document: {"document": {"referenceId": "1234", "name": "LH2.PNG", "contentType": "image/png", "meta": { "imageType": "SIGNATURE","imageIndex": "IMAGE_1"}},"rules": {"workflowName": "LetterheadSignature" }}
attachment: file.PNG

原传递代码如下：

$body = (object)[
    'referenceId' => 'Signature',
    'name' => $filename,
    'contentType' => $filetype,
    'rules' => (object)[
       'workflowName' => 'LetterheadSignature',
    ],
    'meta' => (object)[
       'imageType' => 'SIGNATURE',
       'imageIndex' => 'IMAGE_1',
    ]
];

$sent_data = [
    'document' => json_encode($body),
    'attachment' => $file,
];

$this->apiRequest = $sent_data;

尝试过两种构造$file的方式均失败：

1. Base64编码文件内容：

$handle = fopen($full_filename, "r");
$file_contents = fread($handle, filesize($full_filename));
fclose($handle);
$file = base64_encode($file_contents);

2. 使用curl_file_create：

$file = curl_file_create($full_filename, $filetype, $filename);

其中文件参数定义：

$filename = 'image-of-signature.png';
$filetype = 'image/png';
$full_filename = 'path-to-file' . $filename;

FedEx文档对attachment参数描述为：

string
Input the actual document/file to be uploaded.

问题核心在于两个错误点：

1. document参数的JSON结构不匹配API要求：原代码将rules嵌套在document内部，但API要求document和rules是同级的顶级键。
2. 文件上传需依赖cURL自动处理的multipart/form-data格式：base64编码不符合API对文件参数的要求，必须用curl_file_create传递原始文件对象。

正确的代码示例：

// 1. 构造符合API要求的document JSON结构
$documentData = [
    'document' => [
        'referenceId' => 'Signature',
        'name' => $filename,
        'contentType' => $filetype,
        'meta' => [
            'imageType' => 'SIGNATURE',
            'imageIndex' => 'IMAGE_1'
        ]
    ],
    'rules' => [
        'workflowName' => 'LetterheadSignature'
    ]
];

// 2. 构造请求数据：document为JSON字符串，attachment为curl文件对象
$sent_data = [
    'document' => json_encode($documentData),
    'attachment' => curl_file_create($full_filename, $filetype, $filename)
];

// 3. 初始化cURL并设置参数
$ch = curl_init('https://api.fedex.com/documents/v1/lhsimages/upload');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sent_data);
// 添加FedEx API认证头（替换为你的实际Token）
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_FEDEX_API_TOKEN',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// 执行请求并处理响应
$response = curl_exec($ch);
if(curl_errno($ch)){
    echo 'CURL Error: ' . curl_error($ch);
}
curl_close($ch);

var_dump($response);

关键注意点：

• 严格匹配API的JSON结构：必须保证document和rules是同级的顶级键，不能嵌套。
• 仅使用curl_file_create传递文件：API需要原始文件流，base64编码会导致参数格式不被识别。
• 不要手动设置Content-Type：当CURLOPT_POSTFIELDS为数组时，cURL会自动生成包含boundary的multipart/form-data头，手动设置反而会出错。
• 确认认证头有效：遗漏或错误的Bearer Token也可能触发类似的输入错误提示。

内容的提问来源于stack exchange，提问作者Scott C Wilson