接口名称

跟踪号运输信息查询

接口地址

/api/shipper/v1/track/trackParcel

请求方式

POST

请求头

参数

类型

必填

说明

sessionId

String

否

登录会话ID

language

String

否

语言

Content-Type

String

是

application/json;charset=UTF-8

语言取值：

值

说明

zh_CN

中文

en_US

英文

请求参数

参数

类型

必填

说明

trackingNo

String

是

跟踪号，多个跟踪号用逗号分隔

serverName

String

是

系统主机名称（如：qa.etowertech.com）

trackType

String

否

跟踪类型（可选参数）

请求示例

curl 'https://tracking-qa.etowertech.com/api/shipper/v1/track/trackParcel' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'language: en_US' \
  -H 'sessionId: nfElhOqKga9uSKVeE0CA8w' \
  -d '{
    "trackingNo": "TT010502157GB",
    "serverName": "qa.etowertech.com"
  }'

返回示例

{
  "success": true,
  "code": "0",
  "data": {
    "queryTrackingNos": [
      "TT010502157GB"
    ],
    "missTrackingNos": [],
    "missConsignmentIds": [],
    "trackParcelEvents": [
      {
        "trackingNo": "TT010502157GB",
        "events": [
          {
            "uuid": "mjfQn39ro7raRPZIXLKQYw",
            "trackingNo": "TT010502157GB",
            "eventCode": "SCN",
            "eventTime": "2025-09-17 10:43:12",
            "localTimeZone": "GMT+08:00",
            "activity": "ITEM DESPATCHED TO TRANSSHIPMENT HUB",
            "location": "SHANGHAI",
            "party": 100,
            "facility": "",
            "level": 1,
            "export": false,
            "aggregator": 100,
            "createdBy": 250000100,
            "dateCreated": "2025-09-17 10:43:16",
            "modifiedBy": 250000100,
            "dateModified": "2025-09-17 10:43:16",
            "destCountry": "GB",
            "originCountry": "GB",
            "timestamp": "2025-09-17 10:43",
            "sourceEventCode": "",
            "sourceActivity": "",
            "sourceTrackingNo": ""
          },
          {
            "uuid": "Y6RsdXsvFqgPS5Kmbh5V9Q",
            "trackingNo": "TT010502157GB",
            "eventCode": "LHL",
            "eventTime": "2025-09-17 10:43:00",
            "localTimeZone": "GMT+08:00",
            "activity": "UPLIFTED FROM TRANSSHIPMENT HUB",
            "location": "SHANGHAI",
            "party": 100,
            "level": 1,
            "export": false,
            "aggregator": 100,
            "createdBy": 250000100,
            "dateCreated": "2025-09-17 10:43:56",
            "modifiedBy": 250000100,
            "dateModified": "2025-09-17 10:43:56",
            "destCountry": "GB",
            "originCountry": "GB",
            "timestamp": "2025-09-17 10:43",
            "sourceEventCode": "",
            "sourceActivity": "",
            "sourceTrackingNo": ""
          },
          {
            "uuid": "bcF8ilT_55RrSOWgFk7ogA",
            "trackingNo": "TT010502157GB",
            "eventCode": "RCV",
            "eventTime": "2025-09-16 19:32:14",
            "localTimeZone": "GMT+08:00",
            "activity": "RECEIVED SHIPMENT",
            "location": "SHANGHAI",
            "party": 100,
            "level": 1,
            "export": false,
            "aggregator": 100,
            "createdBy": 250000100,
            "dateCreated": "2025-09-16 19:33:16",
            "modifiedBy": 250000100,
            "dateModified": "2025-09-16 19:33:16",
            "destCountry": "GB",
            "originCountry": "GB",
            "timestamp": "2025-09-16 19:32",
            "sourceEventCode": "",
            "sourceActivity": "",
            "sourceTrackingNo": ""
          },
          {
            "uuid": "6klZsSv4nIN-QExtb9x8iQ",
            "trackingNo": "TT010502157GB",
            "eventCode": "INF",
            "eventTime": "2025-09-16 19:30:27",
            "localTimeZone": "GMT+08:00",
            "activity": "SHIPPING INFORMATION RECEIVED",
            "location": "",
            "party": 100,
            "facility": "",
            "level": 1,
            "export": false,
            "aggregator": 100,
            "createdBy": 0,
            "dateCreated": "2025-09-16 19:30:29",
            "modifiedBy": 0,
            "dateModified": "2025-09-16 19:30:29",
            "destCountry": "GB",
            "originCountry": "GB",
            "timestamp": "2025-09-16 19:30",
            "sourceEventCode": "",
            "sourceActivity": "",
            "sourceTrackingNo": ""
          }
        ],
        "webSites": []
      }
    ]
  },
  "errors": []
}

返回字段说明

字段

类型

说明

success

Boolean

请求是否成功

code

String

响应状态码，"0"表示成功

data

Object

返回数据对象

errors

Array

错误信息列表

data 字段说明

data 对象包含以下字段：

字段

类型

说明

queryTrackingNos

Array

成功查询到的跟踪号列表

trackParcelEvents

Array

成功查询到的包裹事件列表

missTrackingNos

Array

未找到的跟踪号列表

missConsignmentIds

Array

未找到的运单号列表

trackParcelEvents 字段说明

trackParcelEvents 数组中每个对象包含以下字段：

字段

类型

说明

trackingNo

String

跟踪号

events

Array

事件列表

webSites

Array

查询网址列表

events 字段说明

events 数组中每个对象包含以下字段：

字段

类型

说明

uuid

String

事件唯一标识

trackingNo

String

跟踪号

eventCode

String

事件编码（如：INF、RCV、SCN、LHL、DLD、RTN等）

eventTime

String

事件完整时间（格式：YYYY-MM-DD HH:mm:ss）

localTimeZone

String

当地时区（如：GMT+08:00）

activity

String

活动描述

location

String

地点

party

Number

方ID

facility

String

设施

level

Number

级别

export

Boolean

导出标记

aggregator

Number

集成商ID

createdBy

Number

创建者ID

dateCreated

String

创建时间（格式：YYYY-MM-DD HH:mm:ss）

modifiedBy

Number

修改者ID

dateModified

String

修改时间（格式：YYYY-MM-DD HH:mm:ss）

destCountry

String

目的地国家代码

originCountry

String

原始国家代码

timestamp

String

显示时间戳（格式：YYYY-MM-DD HH:mm）

sourceEventCode

String

源事件编码

sourceActivity

String

源活动描述

sourceTrackingNo

String

源跟踪号

webSites 字段说明

webSites 数组中每个对象包含以下字段：

字段

类型

说明

description

String

网站描述

webSite

String

网站URL

枚举值说明

NODES 节点代码配置

节点配置来自文件：src/viewPages/integrator/utils/data/orders/spww.js

NODES: [
  { code: 'INF', id: 'INF', title: i18n.t('nodes.inf'), activity: 'SHIPPING INFORMATION RECEIVED' },
  { code: 'RCV', id: 'RCV', title: i18n.t('nodes.rcv'), activity: 'RECEIVED SHIPMENT' },
  { code: 'SCN', id: 'SCN', title: i18n.t('nodes.scn'), activity: 'ITEM DESPATCHED TO TRANSSHIPMENT HUB' },
  { code: 'LHL', id: 'LHL', title: i18n.t('nodes.lhl'), activity: 'UPLIFTED FROM TRANSSHIPMENT HUB' },
  { code: 'SCN', id: 'SCNDES', title: i18n.t('nodes.scnDes'), activity: '', invented_code: 'SCN_DES' },
  { code: 'DLD', id: 'DLD', title: i18n.t('nodes.dld'), activity: '' }
]

NODES 节点枚举

运输流程中包含以下节点（节点标题来自国际化配置 i18n.t('nodes.xxx')）：

节点ID (id)

事件编码 (code)

虚拟编码 (invented_code)

活动描述 (activity)

国际化Key

节点标题 (title)

INF

INF


SHIPPING INFORMATION RECEIVED

nodes.inf

交运

RCV

RCV


RECEIVED SHIPMENT

nodes.rcv

入库

SCN

SCN


ITEM DESPATCHED TO TRANSSHIPMENT HUB

nodes.scn

出库

LHL

LHL


UPLIFTED FROM TRANSSHIPMENT HUB

nodes.lhl

计划交航

SCNDES

SCN

SCN_DES


nodes.scnDes

目的地扫描

DLD

DLD



nodes.dld

妥投

常见事件编码 (eventCode)

事件编码

英文描述

节点关联

INF

SHIPPING INFORMATION RECEIVED

交运节点 (INF)

RCV

RECEIVED SHIPMENT

入库节点 (RCV)

SCN

ITEM DESPATCHED TO TRANSSHIPMENT HUB

出库节点 (SCN)

SCN

PROCESSED AT ORIGIN HUB

出库节点 (SCN) - 始发仓处理

SCN

WEIGHED AT WAREHOUSE

出库节点 (SCN) - 仓库称重

SCN

DEPARTED FROM ORIGIN PORT

出库节点 (SCN) - 海运离港

SCN

READY TO DEPARTED FROM RAILWAY STATION

出库节点 (SCN) - 铁路发运

SCN

TRANSPORT TO DSTK

出库节点 (SCN) - 运往目的地

LHL

UPLIFTED FROM TRANSSHIPMENT HUB

计划交航节点 (LHL)

DLD

DELIVERED

妥投节点 (DLD)

RTN

RETURN TO SENDER

退回发件人

节点图标点亮逻辑

快速理解

节点点亮的核心逻辑：*遍历接口返回的事件列表，找到与节点配置匹配的事件，如果匹配成功则点亮该节点*。

匹配流程图

┌─────────────────────────────────────────────────────────────┐
│                    节点点亮匹配流程                            │
└─────────────────────────────────────────────────────────────┘

  遍历每个节点配置 (NODES)
         │
         ▼
  初始化节点状态（未点亮）
         │
         ▼
  遍历事件列表 (events)
         │
         ▼
  ┌──────────────────────────────────────────────────────┐
  │  按优先级依次匹配以下规则（一旦匹配成功即停止）         │
  └──────────────────────────────────────────────────────┘
         │
         ├── 规则1: code + activity 双字段精确匹配
         │        适用: 所有节点的标准匹配
         │        示例: eventCode='INF' AND activity='SHIPPING INFORMATION RECEIVED'
         │
         ├── 规则2: code='SCN' + sourceEventCode不为空 + invented_code='SCN_DES'
         │        适用: 目的地扫描节点 (SCNDES)
         │
         ├── 规则3: code='DLD'
         │        适用: 妥投节点 (DLD) - 不校验activity
         │
         ├── 规则4: code匹配 + activity='DEPARTED FROM ORIGIN PORT'
         │        适用: 出库节点 (SCN) - 海运场景
         │
         ├── 规则5: code匹配 + activity='READY TO DEPARTED FROM RAILWAY STATION'
         │        适用: 出库节点 (SCN) - 铁路场景
         │
         └── 规则6: code匹配 + activity='TRANSPORT TO DSTK'
                  适用: 出库节点 (SCN) - 运往目的地
         │
         ▼
  匹配成功？
         │
    ┌────┴────┐
   是         否
    │          │
    ▼          ▼
 点亮节点    继续下一个事件
 (curLight=true)      │
 (arrowLight=true)    ▼
 设置时间戳      继续下一个节点

各节点匹配规则速查表

节点

匹配规则

关键条件

INF

code+activity双匹配

eventCode='INF' AND activity='SHIPPING INFORMATION RECEIVED'

RCV

code+activity双匹配

eventCode='RCV' AND activity='RECEIVED SHIPMENT'

SCN

code+activity双匹配 或 特殊activity

eventCode='SCN' AND (activity='ITEM DESPATCHED...' 或 'DEPARTED...' 或 'READY TO DEPARTED...' 或 'TRANSPORT TO DSTK')

LHL

code+activity双匹配

eventCode='LHL' AND activity='UPLIFTED FROM TRANSSHIPMENT HUB'

SCNDES

特殊匹配

eventCode='SCN' AND sourceEventCode不为空 AND node.invented_code='SCN_DES'

DLD

仅code匹配

eventCode='DLD' (不校验activity)

开发实现要点

1. *节点状态对象结构*

headerLight[nodeId] = {
  arrowLight: false,    // 箭头是否点亮
  curLight: false,      // 当前节点是否点亮
  timestamp: '',        // 点亮时间
  title: node.title     // 节点标题
}

2. *核心匹配伪代码*

foreach (node in NODES) {
  foreach (event in events) {
    // 规则1: 标准双字段匹配
    if (node.code == event.eventCode && node.activity == event.activity) {
      点亮节点; break;
    }
    // 规则2: 目的地扫描特殊匹配
    else if (node.code == event.eventCode
             && event.sourceEventCode不为空
             && node.invented_code == 'SCN_DES') {
      点亮节点; break;
    }
    // 规则3: DLD仅code匹配
    else if (node.code == event.eventCode && event.eventCode == 'DLD') {
      点亮节点; break;
    }
    // 规则4-6: SCN特殊activity匹配
    else if (node.code == event.eventCode
             && activity in ['DEPARTED FROM ORIGIN PORT', 'READY TO DEPARTED FROM RAILWAY STATION', 'TRANSPORT TO DSTK']) {
      点亮节点; break;
    }
  }
}

3. *点亮节点的操作*

hasNode = true;
event = 匹配到的event对象;
headerLight[nodeId].arrowLight = true;
headerLight[nodeId].curLight = true;
headerLight[nodeId].timestamp = event.timestamp;

4. *特殊处理*

箭头点亮逻辑

节点时间戳显示

图标资源说明

每个节点有两套图标：未点亮状态和点亮状态

节点

未点亮图标

点亮图标

INF

INF.png

INF_g.png

RCV

RCV.png

RCV_g.png

SCN

SCN.png

SCN_g.png

LHL

LHL.png

LHL_g.png

SCN_DES

SCN_DES.png

SCN_DES_g.png

DLD

DLD.png

DLD_g.png

箭头

proce-icons.png

proce-icons-success.png