使用php-ups-api实现UPS退货服务时遇三类报错求助

报错1：Invalid merchandise description of package (120623) #

这个错误是因为UPS要求退货包裹必须提供有效的商品描述，你当前代码仅设置了退货服务，未给包裹添加商品描述字段。解决方法是给每个退货包裹补充Description：

if (isset($return_order) && $return_order==1) {
  $returnService = new \Ups\Entity\ReturnService;
  $returnService->setCode(\Ups\Entity\ReturnService::PRINT_RETURN_LABEL_PRL);
  $shipment->setReturnService($returnService);
  
  // 替换为你的实际商品描述，需清晰准确，不能为空或含特殊字符
  $shipment->getPackages()[0]->setDescription('Customer return: Men\'s cotton t-shirt');
}

报错2：Shipment/ReferenceNumber is not allowed for this shipment (120541) #

UPS退货服务不允许在运单（Shipment）级别添加参考号，仅支持在包裹（Package）级别设置。你之前用$shipment->setReferenceNumber($referenceNumber)的写法不符合规则，需将参考号绑定到包裹上。

报错3：再次触发Invalid merchandise description of package (120623) #

第三个代码中你已将参考号移至包裹级别，但仍触发该错误，说明核心问题还是包裹未设置有效商品描述，和参考号无关。只需给包裹补充Description字段即可解决。

完整退货场景代码示例 #

if (isset($return_order) && $return_order==1) {
    // 设置退货服务
    $returnService = new \Ups\Entity\ReturnService;
    $returnService->setCode(\Ups\Entity\ReturnService::PRINT_RETURN_LABEL_PRL);
    $shipment->setReturnService($returnService);
    
    // 设置包裹级别的退货授权参考号
    $referenceNumber = new \Ups\Entity\ReferenceNumber;
    $referenceNumber->setCode(\Ups\Entity\ReferenceNumber::CODE_RETURN_AUTHORIZATION_NUMBER);
    $referenceNumber->setValue($shipping_reference_number);
    $shipment->getPackages()[0]->setReferenceNumber($referenceNumber);
    
    // 必须添加的包裹商品描述
    $shipment->getPackages()[0]->setDescription('Customer return: [你的商品具体描述]');
} else {
    // 普通运单可在运单级别设置参考号
    $referenceNumber = new \Ups\Entity\ReferenceNumber;
    $referenceNumber->setCode(\Ups\Entity\ReferenceNumber::CODE_INVOICE_NUMBER);
    $referenceNumber->setValue($shipping_reference_number);
    $shipment->setReferenceNumber($referenceNumber);
    
    // 普通运单建议补充包裹描述，避免潜在报错
    $shipment->getPackages()[0]->setDescription('Regular shipment: [你的商品具体描述]');
}

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