快递查询 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. 响应字段说明
•  
• 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": []
  }

•