FedEx Trade Document Upload API问题：无法上传签名/信头图片

问题背景 #

集成FedEx REST API时，调用LHImages图片上传端点（用于ETD商业发票的自定义信头/签名）始终返回1001错误，提示Invalid request: invalid input : WorkFlow Name。已成功调用ETDS文档上传端点，但两种请求体结构（自定义结构、官方沙箱示例结构）均触发相同错误。

排查与解决方案 #

1. 确认Workflow Name的有效值 #

FedEx的LHImages API对workflowName有严格的枚举限制，官方文档/示例可能存在不一致情况：

• 避免使用LetterheadSignature（这可能是ETDS文档上传的有效值，而非LHImages的）
• 尝试以下沙箱环境常用有效值：
  • 上传信头：LETTERHEAD
  • 上传签名：SIGNATURE
  • 同时上传信头+签名：LETTERHEAD_AND_SIGNATURE

2. 修正请求体结构 #

确保document的JSON结构正确，rules是document的子节点，且与meta.imageType匹配：

正确的form-data请求体示例

• attachment：选择PNG格式的图片文件（确保文件MIME类型为image/png）
• document（文本类型）：

{
  "referenceId": "12345",
  "name": "IMAGE_1_LETTERHEAD.PNG",
  "contentType": "image/png",
  "meta": {
    "imageType": "LETTERHEAD",
    "imageIndex": "IMAGE_1"
  },
  "rules": {
    "workflowName": "LETTERHEAD"
  }
}

3. 验证请求参数一致性 #

• 确保x-customer-transaction-id请求头的值与document.referenceId完全一致（错误返回中曾出现两者不匹配的情况，需避免）
• 确认Authorization的Bearer Token是沙箱环境的有效令牌

4. 检查文件合规性 #

• 上传的图片必须是PNG格式，分辨率、文件大小需符合FedEx要求（通常不超过5MB，分辨率建议300DPI以内）
• 文件名避免特殊字符，与document.name保持一致

若问题仍存在 #

直接联系FedEx开发者支持，确认沙箱账号的权限范围及LHImages API的workflowName枚举值列表——部分沙箱环境可能对有效值有特殊限制。

内容的提问来源于stack exchange，提问作者Ying Ru Fang