快递查询 API 接口

本文档将帮助您快速了解和使用产品功能。目前版本为1.x版本，后续会根据需要对API版本进行持续更新迭代。

realtime 实时查询接口，实时获取快递数据

一、发起请求:

• 请求允许以HTTP或HTTPS协议进行发送。
•  
• 1. 完整链接
• HTTPS： https://api.toolstip.cn/v1/tracking/realtime
• HTTP： http://api.toolstip.cn/v1/tracking/realtime
•  
• 2. 请求头
• 所有请求的头部都必须包含名为 Toolstip-Api-Key 的键，其对应值是你的 API Key。
• 表头中 Content-Type 对应值必须为 application/json，Content-Type 默认提供 UTF-8 格式的字符集参数，其他编码格式都不支持。
•  

• 	
  Content-Type: application/json 
  Toolstip-Api-Key: YOUR_API_KEY
  
  

•  
• 3. 请求参数
•  

• 字段	描述
  express	必须 ，快递公司简码，示例：美国邮政的简码为 usps ，查看 简码列表
  number	必须，快递单号，示例：快递单号为 9200190404990000471465

二、请求示例

• curl -X POST -k "https://api.toolstip.cn/v1/tracking/realtime" 
  -H "Content-Type:application/json" 
  -H "Toolstip-Api-Key:YOUR_API_KEY" 
  -d '{"express":"usps","number":"9200190404990000471465"}'

三、响应示例

• 请求允许以HTTP或HTTPS协议进行发送。
•  
• 1. 响应字段说明
•  

• 字段	描述
  origin	快递发件地/发件国家
  destination	快递目的地/目的国家
  code	快递物流商简码
  track_number	快递单号，示例：美国邮政的示例快递单号为 9200190404990000471465
  status	快递状态，示例：Delivered
  status_number	快递状态数值，示例：4（代表签收）

•  
• 2. 200响应示例

• {
  	"meta": {
  		"code": 200,
  		"type": "Success",
  		"message": "获取数据成功"
  	},
  	"data": {
  		"name": "美国邮政",
  		"code": "usps",
  		"origin": "",
  		"destination": "",
  		"status": "Created Order",
  		"status_number": 9,
  		"info": [{
  			"date": "2025-11-17 19:31:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "USPS electronic data indicates receipt of your package at our Self-Service Kiosk (SSK) in RONKONKOMA, NY 11779 on November 17, 2025 at 7:31 pm.",
  			"status": "Created Order",
  			"is_date": 1
  		}, {
  			"date": "2025-11-14 02:32:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Shipping Label Created, USPS Awaiting Item, 11\/14\/2025, 2:32 am, BRENTWOOD, NY 11717",
  			"status": "Created Order"
  		}],
  		"update_at": "2026-01-19 15:46:16",
  		"last_event": "2025-11-17 19:31:00,,,,USPS electronic data indicates receipt of your package at our Self-Service Kiosk (SSK) in RONKONKOMA, NY 11779 on November 17, 2025 at 7:31 pm.,Created Order,1"
  	},
  	"error": []
  }

•  
• 3. 异常响应示例

• {
  	"meta": {
  		"code": 202,
  		"type": "Success",
  		"message": "暂无符合条件的数据"
  	},
  	"data": [],
  	"error": []
  }

•  

get 接口，根据快递单号或时间条件获取已经创建的快递记录的数据，最大返回2000条记录

一、发起请求:

• 请求允许以HTTP或HTTPS协议进行发送。
•  
• 1. 完整链接
• HTTPS： https://api.toolstip.cn/v1/tracking/get
• HTTP： http://api.toolstip.cn/v1/tracking/get
•  
• 2. 请求头
• 所有请求的头部都必须包含名为 Toolstip-Api-Key 的键，其对应值是你的 API Key。
• 表头中 Content-Type 对应值必须为 application/json，Content-Type 默认提供 UTF-8 格式的字符集参数，其他编码格式都不支持。
•  

• 	
  Content-Type: application/json 
  Toolstip-Api-Key: YOUR_API_KEY
  
  

•  
• 3. 请求参数
•  

• 字段	描述
  express	可选 ，快递公司简码，示例：美国邮政的简码为 usps ，查看 简码列表
  number	可选，快递单号，示例：美国邮政的示例快递单号为 9200190404990000471465
  start	可选，创建记录最小时间，日期格式，示例：2022-07-27 12:00，如果number为空，则默认为最近60天
  end	可选，创建记录最大时间，日期格式，示例：2022-08-28 12:00

二、请求示例

• curl -X GET -k "https://api.toolstip.cn/v1/tracking/get?number=9200190404990000471465" 
  -H "Content-Type:application/json" 
  -H "Toolstip-Api-Key:YOUR_API_KEY"

三、响应示例

•  
• 1. 响应字段说明
•  

• 字段	描述
  origin	快递发件地/发件国家
  destination	快递目的地/目的国家
  code	快递物流商简码
  track_number	快递单号，示例：美国邮政的示例快递单号为 9200190404990000471465
  status	快递状态，示例：Delivered
  status_number	快递状态数值，示例：4（代表签收）

•  
• 2. 200响应示例

• {
  	"meta": {
  		"code": 200,
  		"type": "Success",
  		"message": "获取数据成功"
  	},
  	"data": [{
  		"origin": "",
  		"destination": "",
  		"status": "Exception",
  		"status_number": 7,
  		"info": [{
  			"date": "",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "The package associated with this tracking number was found to bear counterfeit postage and is now considered Postal Service property under USPS regulations and will not be delivered. You are encouraged to contact the sender\/merchant and\/or your credit card company, as applicable, to seek a refund or other available recourse.",
  			"status": "Exception"
  		}, {
  			"date": "2025-12-25 00:00:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility, 12\/25\/2025",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-24 00:00:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility, 12\/24\/2025",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-23 18:10:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Departed Post Office, December 23, 2025, 6:10 pm, SEATTLE, WA 98158",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-23 13:18:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "USPS in possession of item, December 23, 2025, 1:18 pm, SEATTLE, WA 98158",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-23 06:06:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility, 12\/23\/2025, 6:06 am",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-23 02:06:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility, 12\/23\/2025, 2:06 am",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-22 22:11:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Departed USPS Regional Facility, 12\/22\/2025, 10:11 pm, METRO NY DISTRIBUTION CENTER",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-21 23:01:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Delayed, in transit to destination, December 21, 2025, 11:01 pm",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-21 22:57:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Delayed, in transit to destination, December 21, 2025, 10:57 pm",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-18 20:56:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "USPS electronic receipt of item for mailing, December 18, 2025, 8:56 pm, RONKONKOMA, NY 11779",
  			"status": "In Transit"
  		}, {
  			"date": "2025-12-17 05:10:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Shipping Label Created, USPS Awaiting Item, 12\/17\/2025, 5:10 am, BRENTWOOD, NY 11717",
  			"status": "Created Order"
  		}],
  		"name": "美国邮政",
  		"code": "usps",
  		"track_number": "9200190406850501455583",
  		"update_at": "2026-01-19 15:17:34",
  		"last_event": ",,,,The package associated with this tracking number was found to bear counterfeit postage and is now considered Postal Service property under USPS regulations and will not be delivered. You are encouraged to contact the sender\/merchant and\/or your credit card company, as applicable, to seek a refund or other available recourse.,Exception"
  	}, {
  		"origin": "",
  		"destination": "",
  		"status": "Delivered",
  		"status_number": 4,
  		"info": [{
  			"date": "2025-11-18 14:13:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Delivered, In\/At Mailbox, Your item was delivered in or at the mailbox at 2:13 pm on November 18, 2025 in BLUFFTON, SC 29910.",
  			"status": "Delivered"
  		}, {
  			"date": "2025-11-17 14:54:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-17 14:03:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Departed USPS Regional Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-16 04:15:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Arrived at USPS Regional Destination Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-15 13:49:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Arrived at USPS Regional Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-14 11:25:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-13 21:26:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "In Transit to Next Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-13 05:56:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Departed USPS Regional Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-12 11:00:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Arrived at USPS Regional Origin Facility",
  			"status": "In Transit"
  		}, {
  			"date": "2025-11-12 10:00:00",
  			"local": "",
  			"city": "",
  			"country": "",
  			"event": "Accepted at USPS Regional Facility",
  			"status": "Created Order"
  		}],
  		"name": "美国邮政",
  		"code": "usps",
  		"track_number": "9500115901785379574701",
  		"update_at": "2026-03-25 16:04:35",
  		"last_event": "2025-11-18 14:13:00,,,,Delivered, In\/At Mailbox, Your item was delivered in or at the mailbox at 2:13 pm on November 18, 2025 in BLUFFTON, SC 29910.,Delivered"
  	}],
  	"error": []
  }

•  
• 3. 异常响应示例

• {
  	"meta": {
  		"code": 202,
  		"type": "Success",
  		"message": "暂无符合条件的数据"
  	},
  	"data": [],
  	"error": []
  }

•