如何将UPS API集成从SOAP迁移至REST API？求一对一对象映射

迁移核心步骤 #

• 先梳理现有SOAP接口的业务场景：不管是快递下单、物流追踪、标签打印还是费率查询，得把每个调用的输入输出逻辑摸透，避免遗漏关键业务流程
• 匹配UPS REST API对应端点：比如SOAP的ProcessShipment对应REST的POST /shipments，SOAP的Track对应REST的GET /track/{trackingNumber}，直接查UPS官方文档就能对应上
• 切换认证方式：SOAP用的WS-Security或者自定义用户名密码头，REST统一用OAuth2.0的client credentials模式——去UPS开发者平台申请client ID和secret，拿access token后每次请求把Authorization: Bearer {token}放在请求头里
• 转换数据格式：把原有的XML请求体转成JSON，注意字段名从SOAP的PascalCase改成REST的camelCase，嵌套结构基本对应，但要去掉SOAP那套Envelope、Body的外层包裹
• 适配错误处理：SOAP返回的是SOAP Fault结构，REST用HTTP状态码+响应体里的错误信息，比如400对应参数错、401是认证失败，得把原来的错误捕获逻辑改成对应HTTP状态码的判断
• 增量测试：先挑单个场景测，比如先跑通物流追踪，确认输入输出和SOAP一致，再逐步覆盖所有业务场景，最后做全链路集成测试

SOAP与REST核心对象映射参考 #

1. 发件人/收件人信息 #

SOAP（XML）示例：

<ShipmentRequest>
  <Shipper>
    <Name>ABC Corp</Name>
    <ShipperNumber>123456</ShipperNumber>
    <Address>
      <AddressLine1>123 Main St</AddressLine1>
      <City>Atlanta</City>
      <StateProvinceCode>GA</StateProvinceCode>
      <PostalCode>30301</PostalCode>
      <CountryCode>US</CountryCode>
    </Address>
  </Shipper>
</ShipmentRequest>

REST（JSON）对应示例：

{
  "shipment": {
    "shipper": {
      "name": "ABC Corp",
      "shipperNumber": "123456",
      "address": {
        "addressLine1": "123 Main St",
        "city": "Atlanta",
        "stateProvinceCode": "GA",
        "postalCode": "30301",
        "countryCode": "US"
      }
    }
  }
}

核心映射：字段名从大驼峰转小驼峰，层级结构完全对应，去掉SOAP的命名空间和外层包裹

2. 包裹信息 #

SOAP（XML）示例：

<Package>
  <PackagingType>
    <Code>02</Code>
    <Description>Package</Description>
  </PackagingType>
  <Dimensions>
    <UnitOfMeasurement>
      <Code>IN</Code>
    </UnitOfMeasurement>
    <Length>10</Length>
    <Width>8</Width>
    <Height>6</Height>
  </Dimensions>
  <PackageWeight>
    <UnitOfMeasurement>
      <Code>LBS</Code>
    </UnitOfMeasurement>
    <Weight>5</Weight>
  </PackageWeight>
</Package>

REST（JSON）对应示例：

{
  "packages": [
    {
      "packagingType": {
        "code": "02",
        "description": "Package"
      },
      "dimensions": {
        "unitOfMeasurement": {
          "code": "IN"
        },
        "length": 10,
        "width": 8,
        "height": 6
      },
      "weight": {
        "unitOfMeasurement": {
          "code": "LBS"
        },
        "value": 5
      }
    }
  ]
}

注意点：REST里包裹是数组packages（支持多包裹），SOAP可能是单个或重复节点；重量字段从PackageWeight/Weight转为weight/value

3. 追踪请求 #

SOAP（XML）示例：

<TrackRequest>
  <Request>
    <TransactionReference>
      <CustomerContext>Track My Package</CustomerContext>
    </TransactionReference>
  </Request>
  <TrackingNumber>1Z999AA10123456784</TrackingNumber>
</TrackRequest>

REST（JSON）对应示例：

{
  "trackingNumber": "1Z999AA10123456784",
  "request": {
    "transactionReference": {
      "customerContext": "Track My Package"
    }
  }
}

映射要点：层级结构对应，字段名驼峰化，REST请求体更简洁，没有SOAP的Envelope/Body外层结构

实战注意事项 #

• 盯紧UPS REST API的版本：不同版本字段可能有差异，尽量用最新稳定版，别用废弃字段
• 确认必填/可选字段：SOAP里的可选字段在REST里可能还是可选，但有些字段在REST里会变成必填，一定要对照官方文档核对
• 统一日期格式：SOAP和REST都用ISO 8601格式（比如2024-05-20T14:30:00Z），别自己搞一套格式
• 先单独测端点：用Postman或curl先把REST端点测通，确认请求响应符合预期后再集成到代码里，减少排查难度

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