一、接口介绍

【支持顺丰！！！全球快递物流查询—物流信息追踪-快递单号查询接口】可根据单号自动识别快递公司，提供同步（实时）查询和异步查询两种方式。支持全球范围内1500多家快递物流公司查询，圆通、申通、中通、韵达、百世、EMS、德邦、蓝桥等快递物流接口查询。同时，异步方式下支持物流轨迹推送等功能，以满足企业对快递物流查询多维度的需求。

二、使用案例截图

调用结果示例

点击【在线调试】

 点击【调用接口】调用效果如图所示

三、API文档

3.1按次计费查询物流

3.1.1接入点说明：

使用快递单号实时查询物流信息轨迹，包括收件、运输、配送情况等。本接入点为阻塞式的同步调用。

3.1.2接口地址：

http[s]://route.showapi.com/2650-3?showapi_appid=替换自己的值&showapi_sign=替换自己的值

3.1.3更新频率:

10分钟

3.1.4返回格式:

 json

3.1.5请求参数

3.1.6返回参数

3.1.7请求代码示例

以下是JAVA代码示例:

//更多说明请访问仓库地址：https://github.com/showapi-public/showapi_sdk_java

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/2650-8","showapi_appid","showapi_sign")

  .addTextPara("com","zhongtong")

  .addTextPara("nu","75450632975559")

  .addTextPara("phone","")

  .post();

System.out.println(res);

3.1.8具体流程说明

本接口使用快递单号及快递公司编码二要素，查询单号物流轨迹。

使用HTTP的get或post请求，以普通表单提交方式，编码：Content-Type=application/x-www-form-urlencoded发送数据，阻塞式调用。其时序图如下3.1.8-1所示：

图3.1.8-1时序图

curl调用时的url如下所示：

curl   "http://route.showapi.com/2650-3?showapi_appid=替换自己的值&com=yuantong&nu=YT4620020577123&phone=&showapi_sign=替换自己的值"

调用超时时间为30秒。

3.1.9使用场景示例图如下

用户在商城后台界面，查询购买的货品物流信息（类似于淘宝用户在后台查看快递单物流）。整体流程如下所示：

3.1.9.1同步查询

3.1.9.2异步查询

异步查询推送说明

推送方式：POST；

推送类型：Content-Type = application/x-www-form-urlencoded;charset=utf-8；

推送格式：

{"result":"{\"queryTimes\":1,\"upgrade_info\":\"\",\"fee_num\":0,\"status\":4,\"expSpellName\":\"zhongtong\",\"msg\":\"查询成功\",\"updateStr\":\"2021-07-07 11:06:56\",\"possibleExpList\":[],\"flag\":true,\"tel\":\"95311\",\"ret_code\":0,\"logo\":\"http://static.showapi.com/app2/img/expImg/zto.jpg\",\"expTextName\":\"中通快递\",\"data\":[{\"context\":\"【金华市】 快件离开 【义乌新科】 已发往 【昆明中转】\",\"time\":\"2021-03-29 17:09:49\"},{\"context\":\"【金华市】 【义乌新科】（0579-82402509、0579-85960530） 的 义乌新科自动分拣（18966053802） 已揽收\",\"time\":\"2021-03-29 17:09:41\"}],\"mailNo\":\"75450632975559\",\"dataSize\":11,\"update\":1625627216749}"}

消息确认：用户服务器收到易源请求后，需要回复一个消息以确认。

此消息需要同时满足以下条件：

- http的返回状态为必须为200；

- http的返回体是：{"success":true} 。

如果不满足上面2个条件则认为失败。失败时易源会重复推送5次，间隔时间分别是2,4,8,16,32分钟。

3.1.10快递状态码

3.2按单计费查询物流

3.2.1接入点说明：

使用快递单号实时查询物流信息轨迹，包括收件、运输、配送情况等。本接入点为阻塞式的同步调用。

更多帮助请查看 https://www.showapi.com/book/view/3157/13

30天内1个快递单多次查询只扣1次费。

3.2.2接口地址：

http[s]://route.showapi.com/2650-8?showapi_appid=替换自己的值&showapi_sign=替换自己的值

3.2.3更新频率:

10分钟

3.2.4返回格式:

 json

3.2.5请求参数

3.2.6返回参数

3.2.7请求代码示例

以下是JAVA代码示例:

//更多说明请访问仓库地址：https://github.com/showapi-public/showapi_sdk_java

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/64-34","showapi_appid","showapi_sign")

  .addTextPara("com","zhongtong")

  .addTextPara("nu","75450632975559")

  .addTextPara("phone","")

  .post();

System.out.println(res);

3.2.8具体流程说明

3.2.8.1介绍

用户使用快递单号及快递公司编码，可同步查询单号物流轨迹。

使用HTTP的get或post请求，以普通表单提交方式，编码：Content-Type=application/x-www-form-urlencoded发送数据，同步阻塞式调用。其流程图如下3.2.8.1-1所示：

图3.2.8.1-1流程图

为什么要用按单查询？

1单在30天内只计费一次，可任意查询。概念清晰，性价比高，便于用户管理成本。

3.2.8.2流程步骤说明

图3.2.8.1-1流程图中第1步

curl调用如下所示：

curl   "http://route.showapi.com/2650/8?showapi_appid=替换己的值&com=zhongtong&nu=75312165465979&phone=&showapi_sign=替换自己的值"

具体参数是：

参数名	描述
com	快递公司编码，使用【工具】查询快递公司列表接口获取。
nu	快递单号。
phone	可选。只对于顺丰单号查询有效。是收件人或发件人的手机号码后4位。如果是顺丰单号，请务必传递本参数。

调用超时时间为30秒。

3.2.8.3按单计费说明

3.2.9使用场景示例图如下

3.3批量提交订单订阅

3.3.1接入点说明:

批量提交快递单号（每次最多提交100单），如果此单物流轨迹有更新，则易源会将物流结果推送至用户定义的回调URL（此URL由"【工具】设置推送回调地址"接入点来设定），直至签收结束。

由于是异步操作，易源加入了多次重试、容错切换等机制，可以大大避免快递查询高峰带来的业务抖动，提高查询成功率。

更多帮助请查看 https://www.showapi.com/book/view/3157/14

推送时，您的服务器需要返回：

1.http返回状态码=200

2.返回体为{"success":true} 或 success 确认收信成功。

3.3.2接口地址:

http[s]://route.showapi.com/64-23?showapi_appid=替换自己的值&showapi_sign=替换自己的值

3.3.3返回格式:

json

3.3.4更新频率:

每个快递被揽收完成，录入相应的快递公司后，官网即可查询到物流信息

3.3.5返回格式:

 json

3.3.6请求参数

3.3.7返回参数

3.3.8请求代码示例

以下是JAVA代码示例:

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/64-23","showapi_appid","showapi_sign")

  .addTextPara("com_nu","")

  .post();

System.out.println(res);

3.3.9具体流程说明

3.3.9.1功能说明

用户提交快递单号及快递公司编码到易源，易源在信息有更新时，将单号物流轨迹POST推送至用户指定的callBackUrl。在物流未签收前，易源会进行多次推送操作。

3.3.9.2使用场景示例图如下

3.3.9.3规范

1、使用步骤

1. 首先设置回调地址。
2. 提交需要推送的快递单号。
3. 异步等待易源post信息到您的callbackUrl。

2、提交规范

使用HTTP的get或post请求，以普通表单提交方式，编码：Content-Type=application/x-www-form-urlencoded发送数据，阻塞式调用。

3、推送规则

（1）每天定时推送，推送时间段为：每天的08:00—22:00，平均每两个小时为一次，每天预计8次。

（2）物流信息有增量变化时才会推送。

（3）物流信息无变化，超过3天，将会推送无变化的信息

4、关键参数com_nu说明

com_nu是一个list结构，其中的每一个object有4个属性：

[{

"com": "shunfeng",

"nu": "299801844590",

"phone": "1234",

"outCode": "任意串，长度小于200字符"

},

{

"com": "shunfeng",

"nu": "299801844592",

"phone": "",

"outCode": "thisismyoutcode"

},

{

"com": "shunfeng",

"nu": "299801844593",

"phone": "",

"outCode": "this is my json string"

}

]

其中每个字段的含义是：

参数名	描述
com	快递公司编码，点此查看列表，也可以使用【工具】查询快递公司列表接口获取。
nu	快递单号。
phone	可选。只对于顺丰单号查询有效。是收件人或发件人的手机号码后4位。如果是顺丰单号，请务必传递本参数。
outCode	比如您在提交查询时，传入outCode=myOrderId123456,那么易源在推送结果到回调URL时，会带上outCode=myOrderId123456给您，便于您做单号对应。 outCode是一个< 200长度的串（也可以是json的string格式），易源回推时将原封返回。

易源在回推单号物流时，会将您提交的outCode值一并提交过来，便于您标识单号身份。

3.3.10注意事项

回复格式

用户服务器收到易源请求后，需要回复一个消息以确认。此消息的2个要求是：

条件名称	描述
http返回状态码	等于200
http返回体	{"success":true} 或 success

如果不满足上面2个条件（且的关系）则认为失败。失败时易源会重复推送5次，间隔时间分别是2,4,8,16,32分钟。

推送的实例

#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

四、工具

4.1查询快递公司列表

4.1.1接入点说明：

可查询易源支持的1500+家快递公司列表。

4.1.2接口地址：

http[s]://route.showapi.com/64-20?showapi_appid=替换自己的值&showapi_sign=替换自己的值

4.1.3返回格式:

 Json

4.1.4更新频率:

新增一个快递时，将会更新一次

4.1.5请求参数

​

4.1.6返回参数

​

4.1.7请求代码示例

以下是JAVA代码示例:

//更多说明请访问仓库地址：https://github.com/showapi-public/showapi_sdk_java

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/64-20","showapi_appid","showapi_sign")

  .addTextPara("expName","风")

  .addTextPara("maxSize","")

  .addTextPara("page","")

  .post();

System.out.println(res);

4.1.8返回示例

{

  "showapi_res_error": "",

  "showapi_res_code": 0,

  "showapi_res_id": "60ebb1770de3761e66738645",

  "showapi_res_body": {

    "ret_code": 0,

    "express_list": [

      {

        "img_url": "http://static.showapi.com/app2/img/expImg/shunfeng.jpg",

        "phone": "95338",

        "exp_name": "顺丰速运",

        "com": "shunfeng",

        "url": "http://www.sf-express.com",

        "note": ""

      }

    ],

    "msg": "查询成功!"

  }

}                   

4.2单号查快递公司

4.2.1接入点说明：

通过单号推测其所属的快递公司列表,以可能性大小逆序排序

4.2.2接口地址：

http[s]://route.showapi.com/64-21?showapi_appid=替换自己的值&showapi_sign=替换自己的值

4.2.3返回格式:

 Json

4.2.4更新频率:

立即返回结果数据未做缓存，返回的是最新实时数据

4.2.5请求参数

​

4.2.6返回参数

​

4.2.7请求代码示例

以下是JAVA代码示例:

//更多说明请访问仓库地址：https://github.com/showapi-public/showapi_sdk_java

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/64-21","showapi_appid","showapi_sign")

  .addTextPara("nu","SF1163287169821")

  .addTextPara("addOther","1")

  .post();

System.out.println(res);

4.2.8返回示例

{

       "showapi_res_code": 0,

       "showapi_res_error": "",

       "showapi_res_id":"ce135f6739294c63be0c021b76b6fbff",

    "showapi_res_body": {

              "ret_code": 0,

              "data": [

                     {

                            "simpleName": "zhongtong",

                            "expName": "中通快递"

                     },

        {

                            "simpleName": "shunfeng",

                            "expName": "顺丰速运"

                     }

              ],

              "msg": "操作成功!"

       }

}

4.3设置推送回调地址

4.3.1接入点说明：

快递单有更新时，易源主动将全量物流轨迹以POST请求到此URL。本接入点负责设置/修改此URL

4.3.2接口地址：

http[s]://route.showapi.com/64-22?showapi_appid=替换自己的值&showapi_sign=替换自己的值

4.3.3返回格式:

 Json

4.3.4更新频率:

立即返回结果数据未做缓存，返回的是最新实时数据

4.3.5请求参数

​

4.3.6返回参数

​

4.3.7请求代码示例

以下是JAVA代码示例:

//更多说明请访问仓库地址：https://github.com/showapi-public/showapi_sdk_java

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/64-22","showapi_appid","showapi_sign")

  .addTextPara("callBackUrl","")

  .post();

System.out.println(res);

4.3.8返回示例

       {

  "showapi_res_error": "",

  "showapi_res_id": "f34ae19c68b447d48ebc7ed0b67107a1",

  "showapi_res_code": 0,

  "showapi_res_body": {

    "ret_code": 0,

    "updateTime": "1561711425361",

    "showapi_fee_code": 0,

    "callback_method": "get",

    "callback_url": "http://xxxxxx.com/ForTest/dodo",

    "updateTimeStr": "2019-06-28 16:43:45.045",

    "msg": "成功"

  }

}

4.4查询快递网点

4.4.1接入点说明：

通过网点名称、网点地址、联系电话等查询网点信息

4.4.2接口地址：

http[s]://route.showapi.com/64-36?showapi_appid=替换自己的值&showapi_sign=替换自己的值

4.4.3返回格式:

 Json

4.4.4更新频率:

每年12月1日凌晨1点整更新一次

4.4.5请求参数

​

4.4.6返回参数

​

​

4.4.7请求代码示例

以下是JAVA代码示例:

//更多说明请访问仓库地址：https://github.com/showapi-public/showapi_sdk_java

//这里需要替换为你自己的showapi_appid和showapi_sign，你可以在这里找到 https://www.showapi.com/console#/myApp

String res=new ShowApiRequest("http://route.showapi.com/64-36","showapi_appid","showapi_sign")

  .addTextPara("siteName","小西门")

  .addTextPara("addr","")

  .post();

System.out.println(res);

4.4.8返回示例

  {

  "showapi_res_error": "",

  "showapi_res_code": 0,

  "showapi_res_id": "608227268d57ba3e701d0ca5",

  "showapi_res_body": {

    "ret_code": 0,

    "flag": true,

    "siteList": [

      {

        "com": "yunda",

        "remark": "",

        "tel": "15287171701",

        "lng": "102.68115",

        "city": "昆明市",

        "address": "云南省昆明市西山区金碧街道西园路268号",

        "serviceTime": "",

        "name": "云南昆明五华区小西门公司西园路寄存点分部",

        "province": "云南省",

        "expTextName": "韵达速递",

        "linkman": "徐毅",

        "district": "西山区",

        "lat": "25.04222"

      },

      {

        "com": "shunfeng",

        "address": "新疆维吾尔自治区乌鲁木齐市天山区新华南路街道河滩南路288号",

        "serviceTime": "09:00-19:00",

        "tel": "0991-8890095",

        "name": "小西门速运营业点",

        "province": "新疆维吾尔自治区",

        "expTextName": "顺丰速运",

        "lng": "87.6072259779655",

        "linkman": "张炜",

        "district": "天山区",

        "lat": "43.7962712434222",

        "city": "乌鲁木齐市"

      },

      {

        "com": "yunda",

        "remark": "",

        "tel": "18167977461",

        "lng": "87.61755",

        "city": "乌鲁木齐市",

        "address": "新疆维吾尔自治区乌鲁木齐市天山区解放南路街道人民路育才巷32号",

        "serviceTime": "",

        "name": "新疆主城公司乌鲁木齐小西门服务部",

        "province": "新疆维吾尔自治区",

        "expTextName": "韵达速递",

        "linkman": "裴明明",

        "district": "天山区",

        "lat": "43.79126"

      }

    ]

  }

}

五、数据加密传输

除了使用默认的HTTPS证书加密传输以外，还可以对输入输出字段做业务级的单独加密。

• 加密算法：AES/ECB/PKCS5Padding，AES结果全大写，使用base64编码。密钥由双方线下约定。
• 客户端对所有输入字段进行单独加密。
• 服务端输出加密字段showapi_res_encryption，它是一个base64串，解密后将其反序列化为json对象，对象字段与文档中的返回字段一致。

五、附件

5.1按次及按单返回示例

{

  "showapi_res_error": "",

  "showapi_res_code": 0,

  "showapi_res_id": "5ea916438d57baae126d08d7",

  "showapi_res_body": {

    "update": 1588071235436,

    "upgrade_info": "",

    "updateStr": "2020-04-28 18:53:55",

    "logo": "http://app2.showapi.com/img/expImg/zto.jpg",

    "dataSize": 11,

    "status": 4,

    "fee_num": 1,

    "tel": "95311",

    "data": [

      {

        "time": "2019-11-16 21:33:56",

        "context": "快件已在 【九江城西港】 签收, 签收人: 速递易, 如有疑问请电联:（15779254414）, 投诉电话:（13687028760）, 您的快递已经妥投。风里来雨里去, 只为客官您满意。上有老下有小, 赏个好评好不好？【请在评价快递员处帮忙点亮五颗星星哦~】"

      },

      {

        "time": "2019-11-16 07:31:24",

        "context": "【九江城西港】 的程继业（15779254414） 正在第1次派件, 请保持电话畅通,并耐心等待（95720为中通快递员外呼专属号码，请放心接听）"

      },

      {

        "time": "2019-11-16 07:31:23",

        "context": "快件已经到达 【九江城西港】"

      },

      {

        "time": "2019-11-15 19:06:30",

        "context": "快件离开 【九江】 已发往 【九江城西港】"

      },

      {

        "time": "2019-11-15 19:06:18",

        "context": "快件已经到达 【九江】"

      },

      {

        "time": "2019-11-15 10:45:21",

        "context": "快件离开 【南昌中转部】 已发往 【九江】"

      },

      {

        "time": "2019-11-15 08:02:44",

        "context": "快件已经到达 【南昌中转部】"

      },

      {

        "time": "2019-11-13 15:19:48",

        "context": "快件离开 【石家庄】 已发往 【南昌中转部】"

      },

      {

        "time": "2019-11-13 14:22:09",

        "context": "快件已经到达 【石家庄】"

      },

      {

        "time": "2019-11-13 14:08:31",

        "context": "快件离开 【石家庄市场部】 已发往 【石家庄】"

      },

      {

        "time": "2019-11-13 10:27:33",

        "context": "【石家庄市场部】（0311-68026565、0311-68026566） 的 付保文四组（031186891089） 已揽收"

      }

    ],

    "expSpellName": "zhongtong",

    "msg": "查询成功",

    "mailNo": "75312165465979",

    "queryTimes": 1,

    "ret_code": 0,

    "flag": true,

    "expTextName": "中通快递",

    "possibleExpList": []

  }

}

                    

​