## <font style="background-color:#52C41A;"> </font> 功能说明
:::tips
**<font style="color:black;">实时查询</font>**<font style="color:black;">物流轨迹信息</font>

[及时查询-快速入门](https://www.yuque.com/kdnjishuzhichi/tcyzry/futaqg1wvkpy08iv)👈

:::

:::tips
💡  如已购买付费套餐，且之前使用过免费查询套餐，请将**RequestType**入参修改为**8001**<font style="color:#585A5A;">（原1002）</font>

:::

_<font style="color:#585A5A;">如您第一次使用快递鸟，请参考</font>_[_<font style="color:#117CEE;">API参数示意图</font>_](https://www.yuque.com/kdnjishuzhichi/dfcrg1/hl2gthcuqft7rm34)

## <font style="background-color:#52C41A;"> </font> 接口信息
| **RequestType **<font style="color:#585A5A;">接口指令</font> | **<font style="color:#0070C0;">8001</font>** |
| --- | --- |
| **<font style="color:black;">批量请求</font>** | <font style="color:black;">不支持</font>，并发20次/秒 |
| **<font style="color:black;">计费规则</font>** | <font style="color:#585A5A;">40个自然日内同一（物流编码+单号）不限查询次数，计费1单；</font><br/><font style="color:#585A5A;">查询无轨迹不计费</font> |
| **轨迹排序** | 默认按照发生时间的**升序**排列 |
| **<font style="color:black;">接口地址</font>** | https://api.kdniao.com/api/dist |


## <font style="background-color:#52C41A;"> </font> 支持情况
:::color1
1.       支持查询国内物流公司轨迹，国际查询支持 DHL、UPS、FEDEX  其他国际物流品牌请选用[**<font style="color:#1890FF;">国际版</font>**](https://www.yuque.com/kdnjishuzhichi/dfcrg1/ckelvt)

2.       [**点击查看-支持的快递公司列表**](https://www.yuque.com/kdnjishuzhichi/dfcrg1/mza2ln)

3.       顺丰/跨越速运/中通快递：须通过**CustomerName**传正确的**寄件人or收件人**的手机**号码/座机号 后四位**方可查询

:::

##  <font style="background-color:#52C41A;"> </font> 请求示例
```json
JD请求示例：
{
"ShipperCode": "JD",
"LogisticCode": "JDVA00003618100"
}


SF请求示例：
{
"CustomerName": "7781",
"ShipperCode": "SF",
"LogisticCode": "SF00003618100"
}
```

```json
RequestData: {
		"ShipperCode": "SF",
		"LogisticCode": "SF1673179789153",
		"CustomerName": "3202"
	},
DataType: "2",
EBusinessID: "1000000",
DataSign: "M2JmNjI5mYWZkZTFmOTUxNWYwMZTQzOTQyNjczZThTM=",
RequestType: "8001"
```

###  <font style="background-color:#1890FF;"> </font> 应用级参数
| **<font style="color:#FFFFFF;">名称</font>** | **<font style="color:#FFFFFF;">类型</font>****<font style="color:#FFFFFF;">(长度)</font>** | **<font style="color:#FFFFFF;">是否必须</font>** | **<font style="color:#FFFFFF;">描述</font>** |
| --- | --- | --- | --- |
| ShipperCode | <font style="color:#585A5A;">String(10)</font> | - [x] <font style="color:black;"></font> | [《快递公司编码》](https://www.yuque.com/kdnjishuzhichi/dfcrg1/mza2ln) |
| LogisticCode | <font style="color:#585A5A;">String(30)</font> | - [x] <font style="color:black;"></font> | 快递单号 |
| <font style="color:black;">CustomerName</font> | <font style="color:#585A5A;">String(50)</font> | <font style="background:#F8CED3;color:#70000D">顺丰必填</font><br/><font style="background:#C0DDFC;color:#00346B">跨越必填</font><br/><font style="background:#C0CAFC;color:#101E60">中通必填</font> | 寄件人or收件人 **手机号/座机号后四位**<br/>:::danger + 尽量使用**寄件人**尾号<br/>+ 顺丰**可能**用**虚拟号**下单录入系统  作为验证标准<br/>+ 后四位**传值错误无法获取**到轨迹（可能拉取**缓存**）<br/>+ 顺丰后四位正确性可通过微信小程序【顺丰速运+】验证<br/>+ 顺丰/中通 开启隐私保护的订单需要使用寄件人手机尾号或者是隐私号码验证<br/>+ 中通仅支持查询签收后**6个月**内的单号<br/>:::  |
| | | <font style="background:#F6E1AC;color:#664900">菜鸟橙运</font> | 菜鸟橙运分配的**<font style="color:#101E60;">货主编号</font>** |
| <font style="color:black;">Sort</font> | <font style="color:#585A5A;">Int(1)</font> | - [ ]  | <font style="color:black;">轨迹按时间排序，0-升序，1-降序，默认0</font> |
| OrderCode | <font style="color:#585A5A;">String(30)</font> | - [ ]  | 订单编号 |


 

## <font style="background-color:#52C41A;"> </font> 返回参数
当接口返回无轨迹时请参考下表中的**物流状态**和返回**reason**进行处理

| **<font style="color:#FFFFFF;">名称</font>** | **<font style="color:#FFFFFF;">类型</font>****<font style="color:#FFFFFF;">(</font>****<font style="color:#FFFFFF;">字符长度</font>****<font style="color:#FFFFFF;">)</font>** | **<font style="color:#FFFFFF;">是否必须</font>** | **<font style="color:#FFFFFF;">描述</font>** |
| --- | --- | --- | --- |
| EBusinessID | <font style="color:#585A5A;">String(10)</font> | - [x]  | 用户ID |
| ShipperCode | <font style="color:#585A5A;">String(10)</font> | - [x]  | [快递公司编码](https://www.yuque.com/kdnjishuzhichi/dfcrg1/mza2ln) |
| LogisticCode | <font style="color:#585A5A;">String(30)</font> | - [x]  | 快递单号 |
| Success | <font style="color:#585A5A;">Bool</font><font style="color:#585A5A;">(10)</font> | - [x]  | 成功与否<font style="color:#585A5A;">(true/false)</font> |
| Reason | <font style="color:#585A5A;">String(50)</font> | - [ ]  | 失败原因 |
| State | <font style="color:#585A5A;">String(5)</font> | - [x] <font style="color:black;"></font> | [普通物流状态（点击查看）](https://www.yuque.com/kdnjishuzhichi/weubcu/yftcgpzg81sxwigh) |
| StateEx | <font style="color:#585A5A;">String(5)</font> | - [x] <font style="color:black;"></font> | [详细物流状态（点击查看）](https://www.yuque.com/kdnjishuzhichi/weubcu/cti4czvp8hnatgue) |
| Location | <font style="color:#585A5A;">String(20)</font> | - [x] <font style="color:black;"></font> | <font style="color:black;">当前所在城市</font> |
| Traces.<font style="color:#5C8D07;">AcceptTime</font> | <font style="color:#585A5A;">String(32)</font> | - [x]  | 轨迹发生时间，示例：<br/><font style="color:#585A5A;">Thu Mar 30 05:37:57 CST 2023</font> |
| Traces.<font style="color:#5C8D07;">AcceptStation</font> | <font style="color:#585A5A;">String(500)</font> | - [x]  | 轨迹描述 |
| <font style="color:black;">Traces.</font><font style="color:#5C8D07;">Location</font> | <font style="color:#585A5A;">String(20)</font> | - [ ]  | <font style="color:black;">历史节点所在城市</font> |
| Traces<font style="color:#5C8D07;">.Action</font> | <font style="color:#585A5A;">String(50)</font> | - [x]  | 同 **StateEx** |
| Traces.<font style="color:#5C8D07;">Remark</font> | <font style="color:#585A5A;">String(20)</font> | - [ ]  | 备注 |
| OrderCode | <font style="color:#585A5A;">String(30)</font> | - [ ]  | 订单编号 |
| Callback | <font style="color:#585A5A;">String</font><font style="color:#585A5A;">(50)</font> | - [ ]  | 用户自定义回传字段 |
| Station | <font style="color:#585A5A;">String(50)</font> | - [ ]  | 派件网点的名称 |
| StationTel | <font style="color:#585A5A;">String(50)</font> | - [ ]  | 派件网点的电话 |
| ~~StationAdd~~ | ~~<font style="color:#585A5A;">String(50)</font>~~ | - [ ] ~~~~ | ~~派件网点的地址~~ |
| DeliveryMan | <font style="color:#585A5A;">String(50)</font> | - [ ]  | 派件快递员 |
| DeliveryManTel | <font style="color:#585A5A;">String(50)</font> | - [ ]  | 派件快递员手机号 |
| NextCity | <font style="color:#585A5A;">String(50)</font> | - [ ]  | 下一站城市 |


```json
{
	"EBusinessID": "1000000",
	"ShipperCode": "ZTO",
	"LogisticCode": "78474409893076",
	"State": "3",
	"StateEx": "302",
	"Location": "襄阳市",
	"Traces": [{
		"Action": "1",
		"AcceptStation": "【沧州市】 沧州肃宁县（0317-3*）肃宁中通（1551*） 已揽收",
		"AcceptTime": "2025-01-09 19:22:16",
		"Location": "沧州市"
	}, {
		"Action": "2",
		"AcceptStation": "【沧州市】 快件已发往 襄樊转运中心",
		"AcceptTime": "2025-01-09 19:22:25",
		"Location": "沧州市"
	}, {
		"Action": "204",
		"AcceptStation": "【沧州市】 快件已到达 沧衡转运中心",
		"AcceptTime": "2025-01-09 22:18:34",
		"Location": "沧州市"
	}, {
		"Action": "2",
		"AcceptStation": "【沧州市】 快件已发往 武汉转运中心",
		"AcceptTime": "2025-01-09 22:21:49",
		"Location": "沧州市"
	}, {
		"Action": "204",
		"AcceptStation": "【武汉市】 快件已到达 武汉转运中心",
		"AcceptTime": "2025-01-10 23:53:28",
		"Location": "武汉市"
	}, {
		"Action": "2",
		"AcceptStation": "【武汉市】 快件已发往 襄樊转运中心",
		"AcceptTime": "2025-01-11 00:01:55",
		"Location": "武汉市"
	}, {
		"Action": "204",
		"AcceptStation": "【襄阳市】 快件已到达 襄樊转运中心",
		"AcceptTime": "2025-01-11 05:39:44",
		"Location": "襄阳市"
	}, {
		"Action": "2",
		"AcceptStation": "【襄阳市】 快件已发往 襄阳襄州西",
		"AcceptTime": "2025-01-11 05:48:46",
		"Location": "襄阳市"
	}, {
		"Action": "2",
		"AcceptStation": "【襄阳市】 快件已到达 襄阳襄州西",
		"AcceptTime": "2025-01-11 07:44:27",
		"Location": "襄阳市"
	}, {
		"Action": "202",
		"AcceptStation": "【襄阳市】襄阳襄州西 的业务员【张婷,1388*】正在为您派件（95720为中通快递员外呼专属号码，请放心接听，如有问题可联系网点:0710-37*,投诉电话:1860*）",
		"AcceptTime": "2025-01-11 07:44:28",
		"Location": "襄阳市"
	}, {
		"Action": "412",
		"AcceptStation": "【襄阳市】 快件已在 菜鸟 的【襄阳星悦里店】暂放，【取件地址：汉津路26号（进英大酒店旁）】，请及时取件。如有疑问请联系业务员：138*，代理点电话：183*，投诉电话：1860*",
		"AcceptTime": "2025-01-11 09:10:47",
		"Location": "襄阳市"
	}, {
		"Action": "302",
		"AcceptStation": "【襄阳市】 您的快递已签收，签收人在【襄阳星悦里店】取件。如有疑问请联系业务员：13*，代理点电话：183*，投诉电话：186*。感谢使用中通快递，期待再次为您服务！",
		"AcceptTime": "2025-01-14 18:23:15",
		"Location": "襄阳市"
	}],
	"DeliveryManTel": "1388*",
	"Success": true
}
```

```json
{
    "StateEx": "0",
    "LogisticCode": "YT4841733297234",
    "ShipperCode": "YTO",
    "Traces": [],
    "State": "0",
    "EBusinessID": "1617571",
    "Reason": "暂无轨迹信息",
    "Success": true
}
```

