【LMS系统-渠道对接】PSE USPS渠道轨迹接口对接

需求背景

根据 USPS 发布的最新通知，自 2026 年 4 月起，USPS 将对轨迹数据访问增加更严格的安全校验和访问控制。轨迹访问权限将与 Mailer ID（MID） 及数据接收方的授权关系进行绑定。

• 已基于托运人身份，并与对应 MID 建立授权关系的平台或服务商：可继续正常获取轨迹
• 未提供 MID 或未建立授权关系的第三方访问：
  • 可能需要额外签署协议
  • 存在产生额外费用的风险

因此，需要将 PSE 的 USPS 渠道轨迹获取方式 从第三方 17TRACK 抓取，调整为 直接对接 PSE 轨迹接口，以满足 USPS 新规要求，并降低后续费用与合规风险。

需求描述

1. 轨迹获取方式调整

• 改为通过 PSE 提供的 USPS 轨迹接口 直接查询 / 拉取轨迹数据
• 对接文档见附件

2. 适用范围

• 本次仅针对 PSE USPS 渠道 的轨迹获取进行调整
• 不影响其他自提 USPS 渠道当前的轨迹获取方式

技术实现

`text
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 第一阶段 │ │ 第二阶段 │ │ 第三阶段 │
│ 批量请求 API │─────▶│ 加载状态映射表 │─────▶│ 统一解析数据 │
│ (每批 10 个) │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
┌──────────────────────┐
│ 调用方传入参数 │
│ - trackingNumberMap │
│ - apiServiceTracking │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 1. 参数校验 │
│ 检查 cigUser/asPwd│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 2. 生成签名 │
│ MD5(customerCode+ │
│ key+timestamp) │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 3. 分批请求 PSE API │
│ 每批 10 个跟踪号 │
│ HTTP POST + Header│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 4. 收集原始响应数据 │
│ UspsTrackInfo List│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 5. 加载状态映射表 │
│ WmsWpTrackStatusMap│
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 6. 解析并映射状态 │
│ - 创建 WmsWpTrackInfo│
│ - 匹配状态映射 │
│ - 设置系统轨迹代码 │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ 7. 封装返回结果 │
│ TaskResult │
│ - trackingInfo │
│ - errorInfo │
│ - trackingNumbers │
└──────────────────────┘