FedEx ETD API文档上传报错：document参数缺失问题排查

核心问题分析 #

错误提示"Required request part 'document' is not present"的原因：

• 你将document数据嵌套在data字段中传递，但FedEx API要求直接提交名为document的表单字段。
• 手动指定的Content-Type边界与CURL自动生成的不匹配，导致API无法正确解析请求内容。
• CURLFile的参数配置错误，影响文件上传的识别。

具体错误点与修复 #

1. 表单字段名修正
   移除postData中的data键，直接将JSON格式的document数据作为document字段传递。

2. 移除手动设置的Content-Type头
   当CURL的CURLOPT_POSTFIELDS接收数组时，PHP会自动生成正确的multipart/form-data请求头及边界，手动设置反而会导致解析失败。

3. 修正CURLFile参数

   • 第二个参数（content-type）改为application/pdf（对应PDF文件）。
   • 第三个参数是文件名，应设置为实际的文件名（如g_SO-000022647-WAR-2.pdf）。

4. 删除冗余代码
   手动读取文件内容的代码（fopen/fread部分）完全多余，且存在文件名拼写错误（fg_ vs g_），直接删除即可。

修正后的代码 #

$url = "https://documentapitest.prod.fedex.com/sandbox/documents/v1/etds/upload";
$access_token = $authToken;

$headers = array(
  "x-customer-transaction-id: 12XXXXXX",
  "Authorization: Bearer ".$access_token
);

// 构造document的JSON数据（直接用数组转JSON）
$documentData = json_encode(array(
    "workflowName" => "ETDPreshipment",
    "name" => "g_SO-000022647-WAR-2.pdf",
    "contentType" => "application/pdf", // 修正为PDF的content-type
    "meta" => array(
        "shipDocumentType" => "COMMERCIAL_INVOICE",
        "originCountryCode" => "DK",
        "destinationCountryCode" => "BE"
    )
));

$postData = array(
    'document' => $documentData, // 直接使用document作为字段名
    'attachment' => new CURLFile(
        'C:\xampp\htdocs\test\g_SO-000022647-WAR-2.pdf',
        'application/pdf', // 正确的PDF content-type
        'g_SO-000022647-WAR-2.pdf' // 文件名参数
    )
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);

$response = curl_exec($ch);

if ($response === false) {
    echo 'Curl error: ' . curl_error($ch);
    print_r(curl_error($ch));
}

curl_close($ch);
print_r($response);

额外注意事项 #

• 确保$authToken是有效的FedEx API访问令牌。
• 确认文件路径C:\xampp\htdocs\test\g_SO-000022647-WAR-2.pdf正确，文件存在且有读取权限。

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