查询轨迹

通过此接口，可以使用处理号、跟踪号或者客单号查询包裹的轨迹信息。

请求规格说明

请求说明

GET /api/trackPoints?trackingNumber={trackingNumber}

trackingNumber 的值可为处理号、跟踪号或者客单号。

系统以处理号、跟踪号以及客单号的顺序来判定输入值的类型。

注：花括号{}为参数占位符，实际请求中无需传递

返回数据格式说明

名称	类型	描述
Match	string	匹配值类型，只要此值不为 `Unknown`，即表示找到了与输入值匹配的包裹 Unknown: 未能匹配到任何处理号、跟踪号或者客单号 ParcelId: 请求值为处理号 ParcelTrackingNumber: 请求值为包裹跟踪号 ParcelReferenceId: 请求值为包裹的客单号
TrackingNumber	string	请求值
Status	string	包裹投递状态，输入值未匹配到任何包裹时，此值为空 DataReceived: 收到数据 InTransit: 运输途中 DeliveryReady: 到达待取 DeliveryTried: 尝试投递失败。部分渠道会尝试投递数次 Delivered: 已妥投 DeliveryFailed: 投递失败。地址问题、尝试投递数次均失败、收件人搬家或拒收等 Returned: 已退回 Lost: 包裹遗失
TrackSummary	string	轨迹状态概述
PODReady	bool	POD文件是否已就绪，如果为 true，可通过下载 POD 接口下载 POD 文件
DeliveryPhotoReady	bool	投递照片是否已就绪，如果为 true，可通过下载投递照片接口下载投递照片
Metadata	Metadata	包裹元数据，输入值未匹配到任何包裹时，此值为 null
TrackPoints	TrackingPoint[]	轨迹

包裹元数据

名称	类型	描述
TrackItemId	string	包裹处理号
ReferenceId	string	客单号
TrackingNumber	string	包裹最终跟踪号
FlightNumber	string	航班号
ShippingProductId	string	物流产品代码
ShippingServiceId	string	物流服务代码
OriginCountryCode	string	包裹发件人所在国家代码
DestinationCountryCode	string	包裹收件人所在国家代码

包裹轨迹

名称	类型	描述
Time	string	ISO 8601 标准格式化时间
TimeZone	float	轨迹发生地时区，可能为空
Status	string	关键节点状态
StatusType	string	轨迹状态类型
Location	string	地点
Content	string	轨迹内容

返回数据示例

{
	"Data": {
		"Match": "ParcelTrackingNumber",
		"TrackingNumber": "00340434512190159746",
		"Status": "InTransit",
		"TrackSummary": null,
		"PODReady": false,
		"DeliveryPhotoReady": false,
		"Metadata": {
			"TrackItemId": "",
			"ReferenceId": "",
			"TrackingNumber": "",
			"LastMileCarrier": null,
			"LastMile": null,
			"FlightNumber": null,
			"TrackItemType": "Parcel",
			"ShippingProductId": "",
			"ShippingServiceId": "",
			"OriginCountryCode": "CN",
			"DestinationCountryCode": "DE",
			"DeliveredOn": null
		},
		"TrackPoints": [
			{
				"Time": "2025-11-12T11:20:24Z",
				"TimeZone": null,
				"Status": "DataReceived",
				"StatusType": null,
				"Location": "",
				"Content": "Parcel Data Received",
				"VehicleNo": null,
				"LocationDetail": null
			},
			{
				"Time": "2025-11-14T13:50:33Z",
				"TimeZone": 8,
				"Status": "OriginalWarehouseReceive",
				"StatusType": "",
				"Location": "Shenzhen",
				"Content": "Parcel received at Shenzhen Sorting Centre.",
				"VehicleNo": null,
				"LocationDetail": {
					"CountryCode": "CN",
					"State": "Guangdong",
					"City": "Shenzhen",
					"ZipCode": "518000"
				}
			},
			{
				"Time": "2025-11-14T13:50:34Z",
				"TimeZone": 8,
				"Status": "OriginalWarehouseProcess",
				"StatusType": "",
				"Location": "Shenzhen",
				"Content": "Parcel processed at Shenzhen Sorting Centre.",
				"VehicleNo": null,
				"LocationDetail": {
					"CountryCode": "CN",
					"State": "Guangdong",
					"City": "Shenzhen",
					"ZipCode": "518000"
				}
			},
			{
				"Time": "2025-11-14T20:09:07Z",
				"TimeZone": 1,
				"Status": "InTransit",
				"StatusType": null,
				"Location": "",
				"Content": "There is a preferred location/neighbour for this item.",
				"VehicleNo": null,
				"LocationDetail": null
			},
			{
				"Time": "2025-11-15T00:21:14Z",
				"TimeZone": 8,
				"Status": "OriginalWarehouseDeparture",
				"StatusType": "",
				"Location": "Shenzhen",
				"Content": "Parcel departure in Shenzhen Sorting Centre.",
				"VehicleNo": null,
				"LocationDetail": {
					"CountryCode": "CN",
					"State": "Guangdong",
					"City": "Shenzhen",
					"ZipCode": "518000"
				}
			},
			{
				"Time": "2025-11-15T12:30:00Z",
				"TimeZone": 8,
				"Status": "LinehaulAgencyReceive",
				"StatusType": null,
				"Location": "",
				"Content": "Customs declaration completed",
				"VehicleNo": null,
				"LocationDetail": null
			},
			{
				"Time": "2025-11-16T14:00:00Z",
				"TimeZone": 8,
				"Status": "LinehaulAgencyDeparture",
				"StatusType": null,
				"Location": "Linehaul Agent",
				"Content": "Parcel departure in Transit Facility, Parcel Departure",
				"VehicleNo": null,
				"LocationDetail": null
			},
			{
				"Time": "2025-11-16T18:55:00Z",
				"TimeZone": 8,
				"Status": "LinehaulDeparture",
				"StatusType": null,
				"Location": "",
				"Content": "Parcel is leaving Airport, Parcel Leaving Port",
				"VehicleNo": null,
				"LocationDetail": null
			},
			{
				"Time": "2025-11-17T11:41:00Z",
				"TimeZone": 1,
				"Status": "LinehaulArrival",
				"StatusType": null,
				"Location": "",
				"Content": "Parcel arrives at Airport, Parcel Arrival",
				"VehicleNo": null,
				"LocationDetail": null
			},
			{
				"Time": "2025-11-18T19:20:00Z",
				"TimeZone": 1,
				"Status": "CustomsCleared",
				"StatusType": null,
				"Location": "",
				"Content": "Custom clearance completed",
				"VehicleNo": null,
				"LocationDetail": null
			}
		]
	},
	"Succeeded": true,
	"Error": null
}

输入值未匹配到包裹返回数据示例

{
  "Data": {
    "Match": "Unknown",
    "TrackingNumber": "ABCD0123",
    "Status": null,
    "Metadata": null,
    "TrackPoints": []
  },
  "Succeeded": true,
  "Error": null
}