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

原创

快递100API

修改于 2023-09-25 08:46:41

3K0

文章被收录于专栏：程序员也要懂业务程序员也要懂业务

一、接口选用指南

二、快递100信息推送接口

2.1 系统结构与流程

快递信息推送服务由订阅接口、跟踪系统和回调接口组成：贵公司通过本文档的章2.2.1、2.2.2的规范调用订阅接口将要查询、跟踪的运单号（又称“快递单号”、“单号”，下同）提交给快递100，同时按章2.3.1、2.3.2的规范开发一个回调接口，并将回调接口的地址通过章2.2.1的callbackurl字段提交给快递100。快递100接收到后便对这些运单进行跟踪（又称“监控”、“查询”，下同），当运单状态发生变化的时候，快递100便通过调用回调接口将运单的跟踪信息（又称“查询结果”下同）推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。

订阅接口协议我方已定义好，直接按说明提交请求即可，详见下面2.2；
回调接口需要由贵公司按我方协议来开发，协议详见下面2.3。
2.5附录了所有的快递公司编码，如果您需要的公司不在列表中，请直接联系我们添加。

2.2 订阅接口协议

2.2.1订阅请求

注：订阅请求是指由贵公司发起的web请求，用于声明贵公司需要我方帮忙跟踪某个快递公司的某个运单号，一个单号订阅成功一次即可，快递100收到订阅后会对该单号进行监控与推送。订阅相当于一个form request，即用程序模拟一个http页面的form请求，例如：

</form>

说明：

company是公司代码，请参考文档最后（一律小写，要求严格一致）。
number是快递单号，不得长于32位数字和字母的组合，允许“-”字符，其他字符会导致订阅失败。
from是中文的正确地名，建议提供，可不提供，如果提供一定要正确，否则会导致快递单状态误判。格式以中文可阅读识别省-市-区即可，快递100程序会进行智能匹配。
to是中文的正确地名，建议提供，可不提供，提供了该内容可以提升签收状态判断的准确性，有助于区分“签收”与“退签”；另外，快递单到达目的地后会增监控次数，不提供则没有上述服务。格式以中文可阅读识别省-市-区即可，快递100程序会进行智能匹配。
key是由快递100提供的发起方的身份识别标志，不能错（注意大小写），请向快递100业务联系人索要。
parameters是一个可自定义的HashMap.

callbackurl：回调接口的地址，由贵司提供，用于接收我方推送过去的运单跟踪信息，该回调接口的规范约定见2.3说明。必须是公网可访问地址，开发阶段如果无法提供，可采用快递100后台测试页结合本地html页面的方式模拟。
salt：签名用随机字符串（可选），添加此条段后我方会在向贵方推送数据时用此字符串加签名，贵方收到后进行验证。不能有空格和不可见字符，建议每张快递单重复订阅的时候salt相同，避免由于快递单多次订阅导致的签名不一致问题。我方对签名的使用办法见2.3.1说明。
resultv2：高级推送结果，在快递信息的每一行上为您解析了行政区划地址，编码，以及这一行的状态。

该接口一次只能提交一个请求一个单号，如果单量很大，可以考虑适度并发提交。

2.2.2订阅响应报文及错误码解释

我方收到贵方的订阅请求后，会先将单号保存至我方服务器，然后给贵司返回是否订阅成功的报文及代码，贵方需要将这些代码保存至日志，以备对账时使用, ，具体的报文及代码说明如下：

说明：

result: true表示成功，false表示失败
returnCode:

200: 提交成功

701: 拒绝订阅的快递公司

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

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

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

601: POLL:KEY已过期

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

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

2.3 回调接口协议

2.3.1回调请求

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

</form>

说明：

salt:即贵方通过订阅请求提交的salt的内容，详见 2.2.1的说明。
status：

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

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

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

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

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

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

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

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

所以：

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

重要提醒：

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

如果有专门的工作人员，可以:将快递单罗列给工作人员，由工作人员判断此单是否为假单：如果此单是真实单，则将此单重新向快递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且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存。

关于data：我方每次推送的都是完整的、全量的快递查询结果，而不是部分最新、增量的状态。由于同一快递单查询结果的数据源可能变动，不同数据源之间的结果略有差异，建议每次删除旧的数据后再写入新的数据。
时间建议以ftime为准，不要使用time，time的存在仅仅为了兼容。

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

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

说明：

请按另外的附件文档《自助测试教程》进行测试，只有测试通过了才能上线，否则会出现推送失败的情况。若贵方不按上述操作而导致推送失败，我方不会承担何任责任！
result: "true"表示成功，false表示失败
returnCode:

200: 提交成功

500: 服务器错误

其他错误请自行定义

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

其他信息快递100会忽略。

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

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

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

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

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）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）返回带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。所以，如果判断到status=abort且comNew为空，则按见2.3.1最后的关于status字段下【重要提醒】下的说明重新提交订阅；如查判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；如果判断到status=polling且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存
60天状态无变化中止（abort）说明：对贵司提交订阅的快递单号，我们收到后会对其进行持续跟踪，如果快递单一开始有跟踪信息，但从某个节点起连续10天状态不发生变化后，系统自动回调将查询频率为每天一次，直到第60天，这时会给贵方的回调接口发起一次status=abort、message包含“60天”的推送，告知您这张单异常,在推送发出以后，我们将停止对此单进行跟踪。如果您觉得我们的判断有误，可在收到status=abort后隔半小时向我方提交订阅此单进行跟踪（详见1.3.1节最后的“重要提醒”处的提示）。
如果贵公司回调时需要其他参数，请在回调接口的地址（callbackurl字段）上自行添加。
如果贵司在快递单正处于监控过程时（即单号status=polling时）再次提交订阅此快递单号，我方会会做排重处理，即报returnCode=501的错。
对于某次更新推送，如果由于网络问题导致推送失败，我们会每半个小时重新推一次，尝试推3次，如果3次无法成功会放弃这次更新推送，直至下一次更新推送。
如果由于重大事故或其它原因导致长时间无法推送，请48小时以内联系我们，我们可以为您重新推送历史数据。
对于某个单号，当贵方正确提交订阅了后，我们一般会在15分钟左右后进行第一次监控，如果监控到单号本身有了跟踪信息，即进行第一次推送，否则等待一下次监控。此后我们一般每4小时进行一次监控，并会根据单号的状态等因素作调整。。

2.5 快递公司编码

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

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

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

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

三、快递100实时快递查询接口

3.1 查询接口协议

3.1.1查询请求

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

</form>

3.1.2查询返回

（1）查询结果

（2）错误信息代码

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

returnCode:

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

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

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

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

503: 验证签名失败。

3.1.3运单签收状态服务说明

State值表示如下含义：

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

3.2 查询接口并发协议

基于快递公司系统承压能力有限等原因，暂只能为贵司提供1单/秒的查询并发线程量，若贵司向我方的查询并发量超出约定额度，我方会报超并发错误，如下：

超并发提示代码：

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

3.3 快递公司编码

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

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

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

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

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

4.1 作用

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

4.2 费用与权利责任

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

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

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

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