平博 平博PINNACLE平博 平博PINNACLE快递100物流查询接口现已支持1200家常用的快递及物流公司单号查询、快递网点电话查询、快递价格查询、快递网上寄件服务。近期快递100物流查询接口推出针对部分B2C商城以及移动手机应用需要快递单号查询接口的需求开发了免费的快递单号查询接口服务，每日数据传输量近25G,数据存储量近65G,吞吐量近40万条/秒，技术基础过硬！

　　■订阅、更新监控与推送（回调）■最大提交线单/秒（并可根据单量上调）■支持所有快递■返回XML、JSON结果■返回【时间】、【描述】、【签收状态】、【地理位置】、【3天无结果】等全量结果（详见2.3.1）■有更新推送（回调）功能，即当运单有了新的状态，就通过接口推送至贵司的系统或服务器■一个单只要提交一次请求，快递100会向贵方推送多次结果直到单变成签收或关闭■安全机制：授权key认证+自定义回调接口+签名认证+IP名单

　　■电子商务类或有电子商务相关业务的web网站、手机APP应用、html5页面、微信公众号内的商城、ERP等PC端软件系统等■订单页面显示物流跟踪信息■单号信息有变化贵司就能获知的场景，如触发短信物流提醒、APP物流提醒功能■所有运单号自动地更新如发货、在途、疑难、签收、退签（拒收）等状态，从而进行改变订单的状态、筛选异常件、进行数据分析等操作■大批量、高密度地请求的场景

　　■主动请求■提交最大线单/秒■支持所有快递■返回XML、JSON结果■返回【时间】、【描述】、【签收状态】等全量结果（详见3.1.1）□无更新推送功能□提交一次请求，返回一次结果□安全机制：授权key认证+签名认证

　　■非电子商务的网站、APP、软件系统■最终个人用户主动点击才触发请求，如订单页面查询物流跟踪信息□请勿用程序定期自动查询□不支持大批量地、高频率地、重复性地请求

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

　　平博 PINNACLE平博

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

　　不得长于32位数字和字母的组合，允许“-”字符，其他字符会导致订阅失败。

　　是中文的正确地名，建议提供，可不提供，如果提供一定要正确，否则会导致快递单状态误判。格式以中文可阅读识别

　　是中文的正确地名，建议提供，可不提供，提供了该内容可以提升签收状态判断的准确性，有助于区分“签收”与“退签”；另外，快递单到达目的地后会增监控次数，不提供则没有上述服务。格式以中文可阅读识别

　　是由快递100提供的发起方的身份识别标志，不能错（注意大小写），请向快递100业务联系人索要。

　　：回调接口的地址，由贵司提供，用于接收我方推送过去的运单跟踪信息，该回调接口的规范约定见2.3说明。必须是公网可访问地址，开发阶段如果无法提供，可采用快递100后台测试页结合本地html页面的方式模拟。

　　签名用随机字符串（可选），添加此条段后我方会在向贵方推送数据时用此字符串加签名，贵方收到后进行验证。不能有空格和不可见字符，建议每张快递单重复订阅的时候salt相同，避免由于快递单多次订阅导致的签名不一致问题。我方对签名的使用办法见2.3.1说明。

　　：高级推送结果，在快递信息的每一行上为您解析了行政区划地址，编码，以及这一行的状态。

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

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

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

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

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

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

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

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

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

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

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

　　将快递单罗列给工作人员，由工作人员判断此单是否为假单：如果此单是真实单，则将此单重新向快递100提交一次；如果此单是假单，则将此单标记为假单，而且不再将此单提交给快递100。如果没有专门的工作人员，请直接用以下第二种方法进行操作；

　　在收到status=abort而且message中包含“3天”关键字而且comNew为空的提示10分钟后，将此快递单重新向快递100提交订阅，如果重新提交后仍然收到status= abort，则再次重新向快递100提交，如此，在

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

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

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

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

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

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

　　，否则会出现推送失败的情况。若贵方不按上述操作而导致推送失败，我方不会承担何任责任！

　　为了分布查询压力，尽量不要集中提交，建议当产生快递单时就将快递单提交给快递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小时进行一次监控，并会根据单号的状态等因素作调整。。

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

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

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

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

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

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

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

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

　　如果您对电商运营的物流优化有疑问，可以扫码联系我们的产品运营小徐(kuaidi100-API10)，她能为您设计套符合您公司目前运营状况的解决方案，助您降本增效。