[TOC]
#1. 介绍
接口文档：[https://www.showapi.com/apiGateway/view/64/30](https://www.showapi.com/apiGateway/view/64/30 "https://www.showapi.com/apiGateway/view/64/30")
用户使用`快递单号`及`快递公司编码`，可异步查询`单号物流轨迹`。易源将结果POST推送至您提交时指定的callBackUrl。
使用HTTP的get或post请求，以`普通表单`提交方式，编码：`Content-Type=application/x-www-form-urlencoded`发送数据，异步式调用。其`流程图`如下所示：
**为什么要用异步查询？**
1. 我们接入的快递公司有1000多家，每家的支撑能力不一。如果使用同步查询，峰值时有可能压力超标而超时，造成查询失败（虽然不扣费，但体验不好）
2. 部份业务场景可以优化。比如用户到您的系统查询快递，第一次可以用同步查询，之后用定时任务跑异步查询，由易源推送过来的数据存储到您的库中；这样用户第二、三、N次查询就可以从您的库中直接获取。
#2.流程步骤说明
##2.1 [流程图]中第1步
curl调用如下所示：
```
curl "http://route.showapi.com/64-30?showapi_appid=替换自己的值&com=zhongtong&nu=75312165465979&callBackUrl=xxx&phone=&outCode=&showapi_sign=替换自己的值"
```
具体参数是：
[点此到上述界面](https://www.showapi.com/apiGateway/onlineTest?apiCode=64&pointCode=30 "点此到上述界面")
| 参数名 | 描述 |
| ------------ | ------------ |
| com | 快递公司编码，[点此查看列表](https://www.showapi.com/book/view/3157/3 "点此查看列表")，也可以使用[【工具】查询快递公司列表](https://www.showapi.com/apiGateway/view/?apiCode=64&pointCode=20 "【工具】查询快递公司列表")接口获取。 |
| nu |快递单号。 |
| callBackUrl |异步推送时，易源将结果以POST方式提交到此URL地址。此地址是您的服务器URL。 |
| phone |可选。只对于顺丰单号查询有效。是`收件人`或`发件人`的手机号码后4位。如果是顺丰单号，请务必传递本参数。|
| outCode |比如您在提交查询时，传入outCode=myOrderId123456,那么易源在推送结果到回调URL时，会带上outCode=myOrderId123456给您，便于您做单号对应。 outCode是一个< 200长度的串（也可以是json的string格式），易源回推时将原封返回。|
[查看showapi_appid及showapi_sign。](https://www.showapi.com/console#/myApp "查看showapi_appid及showapi_sign。")
更多sdk调用，请[点此查看](https://www.showapi.com/apiGateway/view?apiCode=64 "点此查看")。
##2.2 [流程图]中第2步
`确认收到`的消息由易源返回，其数据示例是：
```json
{
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_res_id": "5f740c278d57baca5cc4adae",
"showapi_res_body": {
"ret_code": 0, //0为成功，非0失败
"fee_num": 0, //表示本次计费为0，等待推送时才判断是否扣费
"msg": "提交成功，请等待回调"
}
}
```
##2.3 [流程图]中第3步
易源发起POST请求，将结果推送至回调callBackUrl。您作为callBackUrl的主人，收到的信息是：
```
#http头
host:129.211.129.137:7243 //易源推送服务器地址，会改变
content-type:application/x-www-form-urlencoded;charset=utf-8
content-length:697
user-agent:lua-resty-http/0.12 (Lua) ngx_lua/10013
#http body
result=%7B%22queryTimes%22%3A1%2C%22upgrade_info%22%3A%22%22%2C%22fee_num%22%3A0%2C%22status%22%3A2%2C%22expSpellName%22%3A%22huitong%22%2C%22msg%22%3A%22%E6%9F%A5%E8%AF%A2%E6%88%90%E5%8A%9F%22%2C%22updateStr%22%3A%222020-11-02%2010%3A47%3A37%22%2C%22outCode%22%3A%22%22%2C%22flag%22%3Atrue%2C%22tel%22%3A%2295320%22%2C%22ret_code%22%3A0%2C%22logo%22%3A%22http%3A%2F%2Fstatic.showapi.com%2Fapp2%2Fimg%2FexpImg%2Fht.jpg%22%2C%22expTextName%22%3A%22%E7%99%BE%E4%B8%96%E5%BF%AB%E9%80%92(%E5%8E%9F%E6%B1%87%E9%80%9A)%22%2C%22data%22%3A%5B%7B%22context%22%3A%22%E3%80%90%E4%B9%89%E4%B9%8C%E8%BD%AC%E8%BF%90%E4%B8%AD%E5%BF%83%E3%80%91%EF%BC%8C%E6%AD%A3%E5%8F%91%E5%BE%80%E3%80%90%E5%A4%A9%E6%B4%A5%E8%BD%AC%E8%BF%90%E4%B8%AD%E5%BF%83%E3%80%91%22%2C%22time%22%3A%222020-11-01%2022%3A57%3A19%22%7D%2C%7B%22context%22%3A%22%E5%88%B0%E3%80%90%E4%B9%89%E4%B9%8C%E8%BD%AC%E8%BF%90%E4%B8%AD%E5%BF%83%E3%80%91%22%2C%22time%22%3A%222020-11-01%2022%3A55%3A13%22%7D%2C%7B%22context%22%3A%22%E3%80%90%E5%85%B0%E6%BA%AA%E3%80%91%EF%BC%8C%E6%AD%A3%E5%8F%91%E5%BE%80%E3%80%90%E9%87%91%E5%8D%8E%E8%BD%AC%E8%BF%90%E4%B8%AD%E5%BF%83%E3%80%91%22%2C%22time%22%3A%222020-11-01%2017%3A56%3A19%22%7D%2C%7B%22context%22%3A%22%E5%88%B0%E3%80%90%E5%85%B0%E6%BA%AA%E9%9B%86%E8%B4%A7%E7%82%B9%E3%80%91%22%2C%22time%22%3A%222020-11-01%2017%3A42%3A28%22%7D%2C%7B%22context%22%3A%22%E3%80%90%E4%B9%89%E4%B9%8C%E9%BE%9A%E5%A4%A7%E5%A1%98%E5%88%86%E9%83%A8-%E4%BC%98%E8%B4%A8%E5%AE%A2%E6%88%B7%E3%80%91%EF%BC%8C%E3%80%90%E5%BC%A0%E6%9F%B3%E5%A9%B7%2F15658902667%E3%80%91%E5%B7%B2%E6%8F%BD%E6%94%B6%22%2C%22time%22%3A%222020-11-01%2017%3A08%3A49%22%7D%5D%2C%22mailNo%22%3A%22557030343293696%22%2C%22possibleExpList%22%3A%5B%5D%2C%22dataSize%22%3A5%2C%22update%22%3A1604285257608%7D
```
推送编码为`x-www-form-urlencoded`，可认为是普通表单的提交信息。只提交了一个`result`字段。如果使用java，其解析伪代码示意如下：
```
String res=request.getParameter("result") //获取参数
JSONObject js_ret=JSON.parse(res) //string解析为JSON对象
```
js_ret的数据结构是：
```json
{
"queryTimes": 1,
"upgrade_info": "",
"fee_num": 0,
"status": 2,
"expSpellName": "huitong",
"msg": "查询成功",
"updateStr": "2020-11-02 10:47:37",
"outCode": "", //与用户提交时的outCode值完全一致
"flag": true,
"tel": "95320",
"ret_code": 0,
"logo": "http://static.showapi.com/app2/img/expImg/ht.jpg",
"expTextName": "百世快递(原汇通)",
"data": [{
"context": "【义乌转运中心】，正发往【天津转运中心】",
"time": "2020-11-01 22:57:19"
}, {
"context": "到【义乌转运中心】",
"time": "2020-11-01 22:55:13"
}, {
"context": "【兰溪】，正发往【金华转运中心】",
"time": "2020-11-01 17:56:19"
}, {
"context": "到【兰溪集货点】",
"time": "2020-11-01 17:42:28"
}, {
"context": "【义乌龚大塘分部-优质客户】，【张柳婷/15658902667】已揽收",
"time": "2020-11-01 17:08:49"
}],
"mailNo": "557030343293696",
"possibleExpList": [],
"dataSize": 5,
"update": 1604285257608
}
```
##2.4 [流程图]中第4步
用户服务器收到易源请求后，需要回复一个消息以确认。此消息的2个要求是：
| 条件名称 |描述 |
| ------------ | ------------ |
| http返回状态码 | 等于200 |
| http返回体 | `{"success":true}` 或 `success` |
如果不满足上面2个条件（且的关系）则认为失败。失败时易源会重复推送5次，间隔时间分别是2,4,8,16,32分钟。
#3. 计费说明
提交查询时不扣费，在回推时才【可能】扣费。扣费依据和同步查询一致，具体如下：
- 查得计费：物流轨迹节点数>0的时，扣费(非顺丰)。
- 同一单号，24小时累计超过10次无效查询就要扣费（非顺丰）。
- 每次查询都扣费（只对顺丰）。
> 为什么顺丰无物流轨迹也会扣费？
答：顺丰官方接口有总量限制。为防止无限制的滥用，因此查询顺丰快递总是计费。
#4. 业务流程示例
以下是一个使用异步查询接口的业务流程：
