快递100快递查询接口(API)接口规范说明文档-详细版

700: 订阅方的订阅数据存在错误（如不支持的快递公司、单号为空、单号超长等）或错误的回调地址

702: POLL:识别不到该单号对应的快递公司

600: 您不是合法的订阅者（即授权Key出错）

601: POLL:KEY已过期

500: 服务器错误（即快递100的服务器出理间隙或临时性异常，有时如果因为不按规范提交请求，比如快递公司参数写错等，也会报此错误）

501:重复订阅（请格外注意，501表示这张单已经订阅成功且目前还在跟踪过程中（即单号的status=polling），快递100的服务器会因此忽略您最新的此次订阅请求，从而返回501。一个运单号只要提交一次订阅即可，若要提交多次订阅，请在收到单号的status=abort或后隔半小时再提交订阅，详见本文档第13页“重要提醒”部份说明）

2.3 回调接口协议2.3.1回调请求

注：回调请求（也称“推送”）是指由快递100向贵司的回调接口发起请求，用于将运单的物流跟踪信息提交给贵司。回调也是相当于一个form request，即由快递100模拟一个如下的http页面的form请求，例如：

说明：

1、当快递单还在监控过程中，则status=polling；

2、当快递单本身为已签收时，status=，即监控结束，表示此单的生命周期已结束；

3、若单号从提交订阅起连续3天都查不到跟踪信息，或单号从某个节点起不再更新并延续了30天，我们就会终止对此单的跟踪，并给贵方的回调接口（）推送message为“3天查询无记录”或“60天无变化时”、status= abort的提醒，即监控中止。

4、一个运单提交给我们后，如果我们连续查了3天都查不到结果，我方会

（1）判断一次贵司提交的快递公司编码是否正确物流信息查询接口，如果正确，给贵司的回调接口（）推送如下信息：

{"message":"3天查询无记录","status":"abort","":"0","comOld":"","comNew":""，"":{"message":"快递公司参数异常：单号不存在或者已经过期","state":"0","data":[],"status":"201","com":"XXXXX","nu":"","ischeck":"0","":""},"":""}

（2）如果我们判断到贵司提交的快递公司编码出错，我们会帮忙用【正确的快递公司编码】+【原来的运单号】重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（）推送带有如下字段的信息：=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（）推送一条含有如下字段的信息：status=abort、=0、comOld为空、comNew=纠正后的快递公司编码：

{"message":"3天查询无记录","status":"abort","":"0","comOld":"","comNew":"ems（此处是示范）"，"":{"message":"快递公司参数异常：单号不存在或者已经过期","state":"0","data":[],"status":"201","com":"XXXXX","nu":"","ischeck":"0","":""},"":""}

所以：

1、如果判断到status=abort且comNew为空，则按下面【重要提醒】所示重新提交订阅；

重要提醒：

对于status= abort而且message中包含“3天”关键字而且comNew为空的快递单，需要增加以下处理逻辑：

如果有专门的工作人员，可以:将快递单罗列给工作人员商务信息网mobile移动站，由工作人员判断此单是否为假单：如果此单是真实单，则将此单重新向快递100提交一次；如果此单是假单，则将此单标记为假单，而且不再将此单提交给快递100。如果没有专门的工作人员，请直接用以下第二种方法进行操作；如果没有专门的工作人员，可以：在收到status=abort而且message中包含“3天”关键字而且comNew为空的提示10分钟后，将此快递单重新向快递100提交订阅，如果重新提交后仍然收到status= abort，则再次重新向快递100提交，如此，在同一月中如果重复提交3~4次都仍然收到status= abort，则此单为假单，不需要再将此单提交给快递100。

对于同一自然月内重复提交的快递单，结算时只计一次费用，对于跨了两个自然月重复提交的结算单，结算两次费用。

2、如果判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；

3、如果判断到status=polling且=1，则此单为纠正公司编码后的跟踪信息，应保存。

2.3.2回调响应报文及错误码解释

当我方调用贵方的回调接口（）时，贵方需要先将我方提交的数据保存至贵方的数据库，接着向我方返回是否成功接收的响应报文及代码，即贵公司直接在回调接口的地址的中填写如下内容：

说明：

200: 提交成功

500: 服务器错误

其他错误请自行定义

result：true表示回调成功,false表示失败，如果提交回调接口的地址失败，30分钟后重新回调，3次仍旧失败的物流信息查询接口，自动放弃。

其他信息快递100会忽略。

2.3.3运单签收状态（已签收、退回等）增值服务说明

默认状态下，在推送时我们提供了ischeck字段表示快递单是否签收（含正常签收，退回签收两种情况），通过state字段提供签收的具体状态，state具体如下：

签收状态服务能够对目前市面上大多数快递单状态进行准确判定。

若state=0,则如下值代表如下状态：

2.4 注意事项贵方必须严格按2.3.1、2.3.2的规范写好贵方的回调接口，尤其是2.3.2中的回调响应，并通过另外的附件文档《自助测试教程》进行测试，只有测试通过后才能上线，否则会出现推送失败的情况。若贵方不按上述操作而导致推送失败，我方不会承担何任责任！为了分布查询压力，尽量不要集中提交，建议当产生快递单时就将快递单提交给快递100，或者定期分批提交。系统查询快递公司数据会在早8点~晚22点之间，凌晨时间一般快递单无太多变化，这段时间的状态变化在早上7~8点统一同步。由于部分快递公司信息更新不及时，部分单会出现时间偏差较大的现象，整体控制偏差时间>4小时的数据小于10%。由于快递公司有1%的数据会出现时间错乱（与当前时间相差几个月或者1年甚至几十年），还有些数据会出现结果顺序错误，故存在少量异常件需要人工关注，在推送信息中abort的需要人工关注（abort场景：3天查无此单，60天状态无变化）。3天均查无此单中止（abort）说明：当您提交的快递单号，我们连续跟踪3天均查不到跟踪信息，我们认为可能是单号对应的包裹还未被快递员送出去、单号过期了或单号是错误的了，这时会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（）返回带有如下字段的信息：=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（）推送带有如下字段的信息：=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（）推送一条含有如下字段的信息：status=abort、=0、comOld为空、comNew=纠正后的快递公司编码。

所以，如果判断到status=abort且comNew为空，则按见2.3.1最后的关于status字段下【重要提醒】下的说明重新提交订阅；如查判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；如果判断到status=polling且=1，则此单为纠正公司编码后的跟踪信息，应保存60天状态无变化中止（abort）说明：对贵司提交订阅的快递单号，我们收到后会对其进行持续跟踪，如果快递单一开始有跟踪信息，但从某个节点起连续10天状态不发生变化后，系统自动回调将查询频率为每天一次，直到第60天，这时会给贵方的回调接口发起一次status=abort、message包含“60天”的推送，告知您这张单异常,在推送发出以后，我们将停止对此单进行跟踪。如果您觉得我们的判断有误，可在收到status=abort后隔半小时向我方提交订阅此单进行跟踪（详见1.3.1节最后的“重要提醒”处的提示）。如果贵公司回调时需要其他参数，请在回调接口的地址（字段）上自行添加。

如果贵司在快递单正处于监控过程时（即单号status=polling时）再次提交订阅此快递单号，我方会会做排重处理，即报=501的错。对于某次更新推送，如果由于网络问题导致推送失败，我们会每半个小时重新推一次，尝试推3次，如果3次无法成功会放弃这次更新推送，直至下一次更新推送。如果由于重大事故或其它原因导致长时间无法推送，请48小时以内联系我们，我们可以为您重新推送历史数据。对于某个单号，当贵方正确提交订阅了后，我们一般会在15分钟左右后进行第一次监控，如果监控到单号本身有了跟踪信息，即进行第一次推送，否则等待一下次监控。此后我们一般每4小时进行一次监控，并会根据单号的状态等因素作调整。。2.5 快递公司编码

注：公司编码请严格使用小写字符

如果您需要的公司不在此列表，请联系快递100业务联系人添加。

**公司编码请严格使用小写字符

见附件《快递100快递公司编码.xlsx》，或者登陆企业账号在后台下载最新表格。

三、快递100实时快递查询接口3.1 查询接口协议3.1.1查询请求

查询请求相当于一个form request，即用程序模拟一个http页面的form请求，例如：

3.1.2查询返回（1）查询结果（2）错误信息代码

返回正确时的内容如上述（1）所示，如果失败，则返回如下信息：

:

400: 提交的数据不完整，或者贵公司没授权

500: 表示查询失败，或没有POST提交

501: 服务器错误，快递100服务器压力过大或需要升级，暂停服务

502: 服务器繁忙，详细说明见2.2《查询接口并发协议》

503: 验证签名失败。

3.1.3运单签收状态服务说明

State值表示如下含义：

签收状态服务能够对目前市面上大多数快递单状态进行准确判定。

3.2 查询接口并发协议

基于快递公司系统承压能力有限等原因快递100快递查询接口(API)接口规范说明文档-详细版，暂只能为贵司提供1单/秒的查询并发线程量，若贵司向我方的查询并发量超出约定额度，我方会报超并发错误，如下：

超并发提示代码：

如果贵公司因为业务量太大而需要提高查询并发量，请跟我方业务联系人协商调整。

3.3 快递公司编码

注：公司编码请严格使用小写字符

如果您需要的公司不在此列表，请联系快递100业务联系人添加。

**公司编码请严格使用小写字符

见附件《快递100公司编码.xlsx》

四、快递100单号归属公司智能判断接口4.1 作用

将运单号通过我们接口提交至我方，我方返回该运单号可能对应的快递公司的列表。贵司可以用于提前判断用户或商家所输入的快递单号所归属的快递公司，以提升商家录入体验，或可用于对商家录入的信息进行提交较验，以减少商家的录入错误。

4.2 费用与权利责任

由于运单号规则不断变化且各个快递公司没有标准、统一的规则，我们现有机制是通过我们积累的海量数据进行智能分析得出相关规则并且每天更新，所以我们无法保证判断准确率能达到100%。为此，本接口免费提供给贵司使用，同时，我方也不会对本接口的准确性、有效性等提供法律层面上的承诺。当然，本接口同时为我方官网所用接口，所以我方会尽力维护。若贵司将此服务向最终用户提供，建议贵司在展现给用户时加上如下提示：

（1）判断结果后加上一句 “由快递100猜测”等带“猜测”字样的文字说明；

（2）所选的公司可由用户重新手动修改；

（3）在判断结果后提示“本结果仅供参考”等文字说明。

4.3 单号归属公司智能判断接口的使用办法4.3.1 请求地址与参数

[单号]&key=[key]

示范：

4.3.2返回结果

示范：

说明：

每一个｛｝表示一个猜测的公司结果，comCode表示猜测的公司编码，公司编码参考附件《快递100公司编码》。

【本文来源于互联网转载，如侵犯您的权益或不适传播，请邮件通知我们删除】