快递100快递查询接口(API)接口规范说明文档-详细版
16lz
2021-04-27
快递100物流查询接口现已支持1200家常用的快递及物流公司单号查询、快递网点电话查询、快递价格查询、快递网上寄件服务。近期快递100物流查询接口推出针对部分B2C商城以及移动手机应用需要快递单号查询接口的需求开发了免费的快递单号查询接口服务，每日数据传输量近25G,数据存储量近65G,吞吐量近40万条/秒，技术基础过硬！
快递信息推送服务由订阅接口、跟踪系统和回调接口组成：贵公司通过本文档的章2.2.1、2.2.2的规范调用订阅接口将要查询、跟踪的运单号（又称“快递单号”、“单号”，下同）提交给快递100，同时按章2.3.1、2.3.2的规范开发一个回调接口，并将回调接口的地址通过章2.2.1的callbackurl字段提交给快递100。快递100接收到后便对这些运单进行跟踪（又称“监控”、“查询”，下同），当运单状态发生变化的时候，快递100便通过调用回调接口将运单的跟踪信息（又称“查询结果”下同）推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。
说明：
说明：
说明：
说明：
签收状态服务能够对目前市面上大多数快递单状态进行准确判定。若state=0,则condition如下值代表如下状态：
返回正确时的内容如上述（1）所示，如果失败，则返回如下信息：returnCode:400: 提交的数据不完整，或者贵公司没授权 500: 表示查询失败，或没有POST提交 501: 服务器错误，快递100服务器压力过大或需要升级，暂停服务 502: 服务器繁忙，详细说明见2.2《查询接口并发协议》 503: 验证签名失败。
签收状态服务能够对目前市面上大多数快递单状态进行准确判定。
如果贵公司因为业务量太大而需要提高查询并发量，请跟我方业务联系人协商调整。
示范：
说明：每一个｛｝表示一个猜测的公司结果，comCode表示猜测的公司编码，公司编码参考附件《快递100公司编码》。
一、接口选用指南
| 接口 | 功能及性能一览 | 适用应用场景 | 计费方式 |
| 快递100信息推送接口（推荐） | ■订阅、更新监控与推送（回调）■最大提交线程数：20单/秒（并可根据单量上调）■支持所有快递■返回XML、JSON结果■返回【时间】、【描述】、【签收状态】、【地理位置】、【3天无结果】等全量结果（详见2.3.1）■有更新推送（回调）功能，即当运单有了新的状态，就通过接口推送至贵司的系统或服务器■一个单只要提交一次请求，快递100会向贵方推送多次结果直到单变成签收或关闭■安全机制：授权key认证+自定义回调接口+签名认证+IP名单 | ■电子商务类或有电子商务相关业务的web网站、手机APP应用、html5页面、微信公众号内的商城、ERP等PC端软件系统等■订单页面显示物流跟踪信息■单号信息有变化贵司就能获知的场景，如触发短信物流提醒、APP物流提醒功能■所有运单号自动地更新如发货、在途、疑难、签收、退签（拒收）等状态，从而进行改变订单的状态、筛选异常件、进行数据分析等操作■大批量、高密度地请求的场景 | ■按单计费，同一个运单同一个月内只计一次费■详细价格见合同1.3说明 |
| 快递100实时快递查询接口 | ■主动请求■提交最大线程数：1单/秒■支持所有快递■返回XML、JSON结果■返回【时间】、【描述】、【签收状态】等全量结果（详见3.1.1）□无更新推送功能□提交一次请求，返回一次结果□安全机制：授权key认证+签名认证 | ■非电子商务的网站、APP、软件系统■最终个人用户主动点击才触发请求，如订单页面查询物流跟踪信息□请勿用程序定期自动查询□不支持大批量地、高频率地、重复性地请求 | |
| 快递100单号归属公司智能判断接口 | ■能智能识别大部份主流的快递公司■传入运单号，返回对应的公司编码 | ■只有单号，不知道或不确定单号属于哪个快递公司 | ■赠送■若不使用上述两种方案，快递100有权取消贵方对本接口的使用权 |
二、快递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 method="post" name="" action=" http://poll.kuaidi100.com/poll"><input type="text" name="schema" value="json" /><input type="text" name="param" value="{"company":"yuantong","number":"12345678","from":"广东省深圳市南山区","to":"北京市朝阳区","key":"XXX ","parameters":{"callbackurl":"您的回调接口的地址，如http://www.您的域名.com/kuaidi?callbackid=...", "salt":"XXXXXXXXXX","resultv2":"1"}}" ></form>| 发起方: | 贵公司，即快递100的客户，又称“贵方”，下同 |
| 请求地址: | http://poll.kuaidi100.com/poll |
| 通信协议: | HTTP |
| 请求类型: | POST |
| 字符集: | utf-8 |
| 请求内容方式一(json格式): | schema= json param={ "company":"ems", //订阅的快递公司的编码，一律用小写字母，见章2.5《快递公司编码》 "number":"em263999513jp", //订阅的快递单号，单号的最大长度是32个字符 "from":"广东省深圳市南山区", //出发地城市，省-市-区，非必填，填了有助于提升签收状态的判断的准确率，请尽量提供。此处示范仅供参考，与实际信息不一定相符。 "to":"北京市朝阳区", //目的地城市，省-市-区，非必填，填了有助于提升签收状态的判断的准确率，且到达目的地后会加大监控频率，请尽量提供。此处示范仅供参考，与实际信息不一定相符。 "key":"XXX ", //授权码，签合同后发放，详请联系 快递100 对接人 www.kuaidi100.com/openapi "parameters":{ "callbackurl":"您的回调接口的地址，如http://www.您的域名.com/kuaidi?callbackid=...", //回调接口的地址 "salt":"XXXXXXXXXX", //签名用随机字符串（可选）"phone":"XXXXXXXXXX", //收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰单号必填，其他快递公司选填。如座机号码有分机号，分机号无需上传。） "resultv2":"1" //添加此字段表示开通行政区域解析功能（仅对开通签收状态服务用户有效），见章2.3.1《回调请求》"autoCom":"1", //添加此字段且将此值设为1，则表示开始智能判断单号所属公司的功能，开启后，company字段可为空,即只传运单号（number字段），我方收到后会根据单号判断出其所属的快递公司（即company字段）。建议只有在无法知道单号对应的快递公司（即company的值）的情况下才开启此功能；"interCom"："1", //添加此字段表示开启国际版，开启后，若订阅的单号（即number字段）属于国际单号，会返回出发国与目的国两个国家的跟踪信息，出发国的跟踪信息见2.3.1中的lastResult元素组，目的国的跟踪信息见2.3.2中的destResult元素组。本功能暂时只支持邮政体系（国际类的邮政小包、EMS）内的快递公司，若单号我方识别为非国际单，即使添加本字段，也不会返回destResult元素组。建议对于附件文档《快递100快递公司编码.xlsx》中有国家编码的公司通道都添加此字段。"departureCountry":"CN", //出发国家编码,非必填，如中国用CN，国家编码表见附件文档《快递100快递公司编码.xlsx》"departureCom":"ems", //出发的快递公司的编码,非必填"destinationCountry":"JP", //目的国家编码,非必填，，如中国用CN，国家编码表见附件文档《快递100快递公司编码.xlsx》"destinationCom":"japanposten", //目的的快递公司的编码,非必填 }} |
| 请求内容方式二(xml格式): | schema= xml param= <?xml version='1.0' encoding='UTF-8'?><orderRequest> <company>ems</company> //订阅的快递公司的编码，一律用小写字母，见章2.5《快递公司编码》 <number>em263999513jp</number> //订阅的快递单号 <from>北京市朝阳区东直门外大街</from> //出发地城市，省-市-区。此处示范仅供参考，与实际信息不一定相符。 <to>广东省深圳市南山区科技园</to> //目的地城市，省-市-区，到达目的地后会加大监控频率。此处示范仅供参考，与实际信息不一定相符。 <key>**********</key> //授权码，签订合同后发放 <parameters><callbackurl>您的回调接口的地址，如http://www.您的域名.com/kuaidi?callbackid=...</callbackurl> //回调接口的地址<salt>XXXXXX</salt> //签名用随机字符串（可选）<mobiletelephone>XXXXXX</mobiletelephone> //收寄件人的移动电话号码（只能填写一个，顺丰单号必填，其他快递公司选填） <resultv2>1</ resultv2> //添加此字段表示开通行政区域解析功能（仅对开通签收状态服务用户有效），见章2.3.1《回调请求》"autoCom":"1", //添加此字段且将此值设为1，则表示开始智能判断单号所属公司的功能，开启后，company字段可为空,即只传运单号（number字段），我方收到后会根据单号判断出其所属的快递公司（即company字段）。建议只有在无法知道单号对应的快递公司（即company的值）的情况下才开启此功能；"interCom"："1", //添加此字段表示开启国际版，开启后，若订阅的单号（即number字段）属于国际单号，会返回出发国与目的国两个国家的跟踪信息，出发国的跟踪信息见2.3.1中的lastResult元素组，目的国的跟踪信息见2.3.2中的destResult元素组。本功能暂时只支持邮政体系（国际类的邮政小包、EMS）内的快递公司，若单号我方识别为非国际单，即使添加本字段，也不会返回destResult元素组。建议对于附件文档《快递100快递公司编码.xlsx》中有国家编码的公司通道都添加此字段。<departureCountry>CN</departureCountry>, //出发国家编码,非必填，如中国用CN，国家编码表见附件文档《快递100快递公司编码.xlsx》<departureCom>ems</departureCom>, //出发的快递公司的编码,非必填<destinationCountry>JP</destinationCountry>, //目的国家编码,非必填，，如中国用CN，国家编码表见附件文档《快递100快递公司编码.xlsx》<destinationCom>japanposten</destinationCom>, //目的的快递公司的编码,非必填</parameters></orderRequest> |
- 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订阅响应报文及错误码解释
我方收到贵方的订阅请求后，会先将单号保存至我方服务器，然后给贵司返回是否订阅成功的报文及代码，贵方需要将这些代码保存至日志，以备对账时使用, ，具体的报文及代码说明如下：| 返回格式方式一（json）： | { "result":true, "returnCode":"200", "message":"提交成功"} |
| 返回格式方式二（xml）： | <?xml version='1.0' encoding='UTF-8'?><orderResponse> <result>true</result> <returnCode>200</returnCode> <message>订阅成功</message></orderResponse> |
- result: true表示成功，false表示失败
- returnCode:
2.3 回调接口协议
2.3.1回调请求
注：回调请求（也称“推送”）是指由快递100向贵司的回调接口发起请求，用于将运单的物流跟踪信息提交给贵司。回调也是相当于一个form request，即由快递100模拟一个如下的http页面的form请求，例如：<form method="post" name="" action="[callbackurl]"><input type="text" name="param" value="{XXX}" ><input type="text" name="sign" value="签名字符串" /></form>| 发起方: | 快递100，又称“我方”，上下文相同 |
| 请求地址: | 由贵司在订阅请求中通过callbackurl字段提供（详见2.2.1说明） |
| 通信协议: | HTTP |
| 请求类型: | POST |
| 字符集: | utf-8 |
| 请求内容方式一：（json格式、无签名认证状态）: | param={"status":"polling", /*监控状态:polling:监控中，shutdown:结束，abort:中止，updateall：重新推送。其中当快递单为已签收时status=shutdown，当message为“3天查询无记录”或“60天无变化时”status= abort ，对于stuatus=abort的状度，需要增加额外的处理逻辑，详见本节最后的说明 */ "billstatus":"got", /*包括got、sending、check三个状态，由于意义不大，已弃用，请忽略*/ "message":"", /*监控状态相关消息，如:3天查询无记录，60天无变化*/ "autoCheck":"1", /*快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码（即2.1中的company字段，下同），1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。所以，如果判断到status=abort且comNew为空，则按见本节最后的关于status字段下【重要提醒】下的说明重新提交订阅；如查判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；如果判断到status=polling且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/"comOld":"yuantong", /*贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/"comNew":"ems"， /*我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/"lastResult":{ /*最新查询结果，若在订阅报文中通过interCom字段开通了国际版，则此lastResult表示出发国的查询结果，全量，倒序（即时间最新的在最前）*/ "message":"ok", /*消息体，请忽略*/ "state":"0", /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */ "status":"200", /*通讯状态，请忽略*/ "condition":"F00", /*快递单明细状态标记，若state=0,则condition如下值代表如下状态：condition=CU001 等待清关condition=CU002 清关中condition=CU003 已清关condition=CU004 清关异常/ "ischeck":"0", /*是否签收标记，明细状态请参考2.3.3节state字段*/ "com":"yuantong", /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/ "nu":"V030344422", /*单号*/ "data":[ {"context":"上海分拨中心/装件入车扫描 ", /*内容*/"time":"2012-08-28 16:33:19", /*时间，原始格式*/"ftime":"2012-08-28 16:33:19", /*格式化后时间*/"status":"在途", /*本数据元对应的签收状态。只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaCode":"310000000000", /*本数据元对应的行政区域的编码，只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaName":"上海市", /*本数据元对应的行政区域的名称，开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/ },{"context":"上海分拨中心/下车扫描 ", /*内容*/"time":"2012-08-27 23:22:42", /*时间，原始格式*/"ftime":"2012-08-27 23:22:42", /*格式化后时间*/"status":"在途", /*本数据元对应的签收状态。只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaCode":"310000000000", /*本数据元对应的行政区域的编码，只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaName":"上海市", /*本数据元对应的行政区域的名称，开通签收状态服务（见上面"status"后后的说明）且在订阅接口中提交resultv2标记后才会出现*/ } ] }, "destResult":{ /*表示最新的目的国家的查询结果，只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元，全量，倒序（即时间最新的在最前）*/"message":"ok", /*消息体，请忽略*/"state":"0", /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态详见章2.3.3 */"status":"200", /*通讯状态，请忽略*/"condition":"F00", /*快递单明细状态标记，暂未实现，请忽略*/"ischeck":"0" ,/*是否签收标记，明细状态请参考2.3.3节state字段*/"com":"speedpost", /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/"nu":"EX015142583SG", /*单号*/"data":[{"context":"[01000]Final delivery Delivered to: SLOVESNOV",/*内容*/"time":"2016-05-24 14:00:00", /*时间，原始格式*/"ftime":"2016-05-24 14:00:00", /*格式化后时间*/"status":"签收" /*本数据元对应的签收状态。只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaCode":null, /*本数据元对应的行政区域的编码，只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaName":null, /*本数据元对应的行政区域的名称，开通签收状态服务（见上面"status"后后的说明）且在订阅接口中提交resultv2标记后才会出现*/}] }} |
| 请求内容方式二：（json格式+签名认证）: | sign=MD5(param+salt)¶m={ "status":"polling", /*监控状态:polling:监控中，shutdown:结束，abort:中止，updateall：重新推送。其中当快递单为已签收时status=shutdown，当message为“3天查询无记录”或“60天无变化时”status= abort ，对于stuatus=abort的状度，需要增加额外的处理逻辑，详见本节最后的说明 */ "billstatus":"got", /*包括got、sending、check三个状态，由于意义不大，已弃用，请忽略*/ "message":"", /*监控状态相关消息，如:3天查询无记录，60天无变化*/ "autoCheck":"1", /*快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码（即2.1中的company字段，下同），1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。所以，如果判断到status=abort且comNew为空，则按见本节最后的关于status字段下【重要提醒】下的说明重新提交订阅；如查判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；如果判断到status=polling且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/"comOld":"yuantong", /*贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/"comNew":"ems"， /*我司纠正后的新的快递公司编码。详细见autoCheck后说明 。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/ "lastResult":{ /*最新查询结果，若在订阅报文中通过interCom字段开通了国际版，则此lastResult表示出发国的查询结果，全量，倒序（即时间最新的在最前）*/ "message":"ok", /*消息体，请忽略*/ "state":"0", /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */ "status":"200", /*通讯状态，请忽略*/ "condition":"F00", /*快递单明细状态标记，若state=0,则condition如下值代表如下状态：condition=CU001 等待清关condition=CU002 清关中condition=CU003 已清关condition=CU004 清关异常*/ "ischeck":"0", /*是否签收标记，明细状态请参考state字段*/ "com":"yuantong", /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/ "nu":"V030344422", /*单号*/ "data":[ {"context":"上海分拨中心/装件入车扫描 ", /*内容*/"time":"2012-08-28 16:33:19", /*时间，原始格式*/"ftime":"2012-08-28 16:33:19", /*格式化后时间*/"status":"在途", /*本数据元对应的签收状态。只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaCode":"310000000000", /*本数据元对应的行政区域的编码，只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaName":"上海市", /*本数据元对应的行政区域的名称，开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/ },{"context":"上海分拨中心/下车扫描 ", /*内容*/"time":"2012-08-27 23:22:42", /*时间，原始格式*/"ftime":"2012-08-27 23:22:42", /*格式化后时间*/"status":"在途", /*本数据元对应的签收状态。只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaCode":"310000000000", /*本数据元对应的行政区域的编码，只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaName":"上海市", /*本数据元对应的行政区域的名称，开通签收状态服务（见上面"status"后后的说明）且在订阅接口中提交resultv2标记后才会出现*/ } ] }, "destResult":{ /*表示最新目的国家的查询结果，只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元，全量，倒序（即时间最新的在最前）*/"message":"ok", /*消息体，请忽略*/"state":"0", /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */"status":"200", /*通讯状态，请忽略*/"condition":"F00", /*快递单明细状态标记，暂未实现，请忽略*/"ischeck":"0" ,/*是否签收标记，明细状态请参考2.3.3节state字段*/"com":"speedpost", /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/"nu":"EX015142583SG", /*单号*/"data":[{"context":"[01000]Final delivery Delivered to: SLOVESNOV",/*内容*/"time":"2016-05-24 14:00:00", /*时间，原始格式*/"ftime":"2016-05-24 14:00:00", /*格式化后时间*/"status":"签收" /*本数据元对应的签收状态。只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaCode":null, /*本数据元对应的行政区域的编码，只有在开通签收状态服务（见上面"status"后的说明）且在订阅接口中提交resultv2标记后才会出现*/"areaName":null, /*本数据元对应的行政区域的名称，开通签收状态服务（见上面"status"后后的说明）且在订阅接口中提交resultv2标记后才会出现*/}] } } |
| 请求内容方式三（xml格式、无签名认证）: | param=<?xml version='1.0' encoding='UTF-8'?><pushRequest> <status>polling</status> /*监控状态:polling:监控中，shutdown:结束，abort:中止，updateall：重新推送。其中当快递单为已签收时status=shutdown，当message为“3天查询无记录”或“60天无变化时”status= abort ，对于stuatus=abort的状度，需要增加额外的处理逻辑，详见本节最后的说明 */ <billstatus>polling</billstatus> /*包括got、sending、check三个状态，由于意义不大，已弃用，请忽略*/ <message>ok</message> /*监控状态相关消息，如:3天查询无记录，60天无变化*/ <autoCheck>1</autoCheck> /*快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码（即2.1中的company字段，下同），1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。所以，如果判断到status=abort且comNew为空，则按见本节最后的关于status字段下【重要提醒】下的说明重新提交订阅；如查判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；如果判断到status=polling且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/<comOld>yuantong</comOld> /*贵司提交的原始的快递公司编码。详细见autoCheck后说明 。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/<comNew>ems</comNew> /*我司纠正后的新的快递公司编码。详细见autoCheck后说明 。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/<lastResult> /*最新查询结果，若在订阅报文中通过interCom字段开通了国际版，则此lastResult表示出发国的查询结果，全量，倒序（即时间最新的在最前）*/ <message>ok</message> /*消息体，请忽略*/ <nu>V030344422</nu> /*单号*/ <ischeck>0</ischeck> /*是否签收标记，明细状态请参考state字段*/ <com>yauntong</com> /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/ <status>200</status> /*通讯状态，请忽略*/ <data> <item> <time>2012-08-28 16:33:19</time> /*时间，原始格式*/ <context>上海分拨中心/装件入车扫描 </context> /*内容*/ <ftime>2012-08-28 16:33:19</ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>310000000000</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>上海市</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item> <item> <time>2012-08-27 23:22:42</time> /*时间，原始格式*/ <context>上海分拨中心/下车扫描</context> /*内容*/ <ftime>2012-08-27 23:22:42</ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>310000000000</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>上海市</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item></data> <state>0</state> /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */ <condition>F00</condition> /*快递单明细状态标记，若state=0,则condition如下值代表如下状态：condition=CU001 等待清关condition=CU002 清关中condition=CU003 已清关condition=CU004 清关异常*/ </lastResult> <destResult> /*表示最新目的国家的查询结果，只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元，全量，倒序（即时间最新的在最前）*/ <message>ok</message> /*消息体，请忽略*/ <nu>EX015142583SG</nu> /*单号*/ <ischeck>0</ischeck> /*是否签收标记，明细状态请参考state字段*/ <com>speedpost</com> /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/ <status>200</status> /*通讯状态，请忽略*/ <data> <item> <time>2016-05-24 14:00:00</time> /*时间，原始格式*/ <context>[01000]Final delivery Delivered to: SLOVESNOV</context> /*内容*/ <ftime>2016-05-24 14:00:00</ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>310000000000</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>上海市</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item> <item> <time> 2016-05-21 16:51:00 </time> /*时间，原始格式*/ <context> Received at Destination Processing Facility </context> /*内容*/ <ftime> 2016-05-21 16:51:00 </ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>null</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>null</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item></data> <state>0</state> /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */ <condition>F00</condition> /*快递单明细状态标记，暂未实现，请忽略*/ </destResult> </pushRequest> |
| 请求内容方式四（xml格式+签名认证）: | sign=MD5(param+salt)¶m=<?xml version='1.0' encoding='UTF-8'?><pushRequest> <status>polling</status> /*监控状态:polling:监控中，shutdown:结束，abort:中止，updateall：重新推送。其中当快递单为已签收时status=shutdown，当message为“3天查询无记录”或“60天无变化时”status= abort ，对于stuatus=abort的状度，需要增加额外的处理逻辑，详见本节最后的说明 */ <billstatus>polling</billstatus> /*包括got、sending、check三个状态，由于意义不大，已弃用，请忽略*/ <message>ok</message> /*监控状态相关消息，如:3天查询无记录，60天无变化*/ <autoCheck>1</autoCheck> /*快递公司编码是否出错，0为本推送信息对应的是贵司提交的原始快递公司编码（即2.1中的company字段，下同），1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果，我方会（1）判断一次贵司提交的快递公司编码是否正确，如果正确，给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=0、comOld与comNew都为空；（2）如果贵司提交的快递公司编码出错，我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控（后续如果监控到单号有更新就给贵司的回调接口（callbackurl）推送带有如下字段的信息：autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码）；并且给贵方的回调接口（callbackurl）推送一条含有如下字段的信息：status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。所以，如果判断到status=abort且comNew为空，则按见本节最后的关于status字段下【重要提醒】下的说明重新提交订阅；如查判断到status=abort且comNew不为空，则不需要重新提交订阅，且将贵司原来的快递公司编码改为comNew后的值，或在贵司数据库中增加一个快递公司编码为comNew+原来单号的运单；如果判断到status=polling且autoCheck=1，则此单为纠正公司编码后的跟踪信息，应保存。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/<comOld>yuantong</comOld> /*贵司提交的原始的快递公司编码。详细见autoCheck后说明 。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/<comNew>ems</comNew> /*我司纠正后的新的快递公司编码。详细见autoCheck后说明 。若开启了国际版（即在订阅请求中增加字段interCom=1），则回调请求中暂无此字段*/ <lastResult> /*最新查询结果，全量，倒序（即时间最新的在最前）*/ <message>ok</message> /*消息体，请忽略*/ <nu>V030344422</nu> /*单号*/ <ischeck>0</ischeck> /*是否签收标记，明细状态请参考state字段*/ <com>yauntong</com> /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/ <status>200</status> /*通讯状态，请忽略*/ <data> <item> <time>2012-08-28 16:33:19</time> /*时间，原始格式*/ <context>上海分拨中心/装件入车扫描 </context> /*内容*/ <ftime>2012-08-28 16:33:19</ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>310000000000</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>上海市</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item> <item> <time>2012-08-27 23:22:42</time> /*时间，原始格式*/ <context>上海分拨中心/下车扫描</context> /*内容*/ <ftime>2012-08-27 23:22:42</ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>310000000000</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>上海市</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item></data> <state>0</state> /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */ <condition>F00</condition> /*快递单明细状态标记，暂未实现，请忽略*/ </lastResult> <destResult> /*表示最新目的国家的查询结果，只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元，全量，倒序（即时间最新的在最前）*/ <message>ok</message> /*消息体，请忽略*/ <nu>EX015142583SG</nu> /*单号*/ <ischeck>0</ischeck> /*是否签收标记，明细状态请参考state字段*/ <com>speedpost</com> /*快递公司编码,一律用小写字母，见章2.5《快递公司编码》*/ <status>200</status> /*通讯状态，请忽略*/ <data> <item> <time>2016-05-24 14:00:00</time> /*时间，原始格式*/ <context>[01000]Final delivery Delivered to: SLOVESNOV</context> /*内容*/ <ftime>2016-05-24 14:00:00</ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>310000000000</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>上海市</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item> <item> <time> 2016-05-21 16:51:00 </time> /*时间，原始格式*/ <context> Received at Destination Processing Facility </context> /*内容*/ <ftime> 2016-05-21 16:51:00 </ftime> /*格式化后时间*/<status>在途</status> /*本<item>对应的签收状态。只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaCode>null</areaCode> /*本<item>对应的行政区域的编码，只有在开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/<areaName>null</areaName> /*本<item>对应的行政区域的名称，开通签收状态服务（见下面<state>后的说明）且在订阅接口中提交resultv2标记后才会出现*/ </item></data> <state>0</state> /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章2.3.3 */ <condition>F00</condition> /*快递单明细状态标记，若state=0,则condition如下值代表如下状态：condition=CU001 等待清关condition=CU002 清关中condition=CU003 已清关condition=CU004 清关异常*/ </destResult> </pushRequest> |
- salt:即贵方通过订阅请求提交的salt的内容，详见 2.2.1的说明。
- status：
- 如果有专门的工作人员，可以:将快递单罗列给工作人员，由工作人员判断此单是否为假单：如果此单是真实单，则将此单重新向快递100提交一次；如果此单是假单，则将此单标记为假单，而且不再将此单提交给快递100。如果没有专门的工作人员，请直接用以下第二种方法进行操作；
- 如果没有专门的工作人员，可以：在收到status=abort而且message中包含“3天”关键字而且comNew为空的提示10分钟后，将此快递单重新向快递100提交订阅，如果重新提交后仍然收到status= abort，则再次重新向快递100提交，如此，在同一月中如果重复提交3~4次都仍然收到status= abort，则此单为假单，不需要再将此单提交给快递100。
- 关于data：我方每次推送的都是完整的、全量的快递查询结果，而不是部分最新、增量的状态。由于同一快递单查询结果的数据源可能变动，不同数据源之间的结果略有差异，建议每次删除旧的数据后再写入新的数据。
- 时间建议以ftime为准，不要使用time，time的存在仅仅为了兼容。
2.3.2回调响应报文及错误码解释
当我方调用贵方的回调接口（callbackurl）时，贵方需要先将我方提交的数据保存至贵方的数据库，接着向我方返回是否成功接收的响应报文及代码，即贵公司直接在回调接口的地址的response中填写如下内容：| 返回格式方式一（json）： | { "result":true, "returnCode":"200", "message":"成功"} |
| 返回格式方式二（xml）： | <?xml version='1.0' encoding='UTF-8'?><pushResponse> <result>true</result> <returnCode>200</returnCode> <message>成功</message></pushResponse> |
- 请按另外的附件文档《自助测试教程》进行测试，只有测试通过了才能上线，否则会出现推送失败的情况。若贵方不按上述操作而导致推送失败，我方不会承担何任责任！
- result: "true"表示成功，false表示失败
- returnCode:
2.3.3运单签收状态（已签收、退回等）增值服务说明
默认状态下，在推送时我们提供了ischeck字段表示快递单是否签收（含正常签收，退回签收两种情况），通过state字段提供签收的具体状态，state具体如下：| 状态值 | 名称 | 含义 | 费用说明 |
| 0 | 在途 | 快件处于运输过程中 | 默认提供 |
| 1 | 揽收 | 快件已由快递公司揽收 | 默认提供 |
| 2 | 疑难 | 快递100无法解析的状态，或者是需要人工介入的状态，比方说收件人电话错误。 | 默认提供 |
| 3 | 签收 | 正常签收 | 默认提供 |
| 4 | 退签 | 货物退回发货人并签收 | 默认提供 |
| 5 | 派件 | 货物正在进行派件 | 默认提供 |
| 6 | 退回 | 货物正处于返回发货人的途中 | 默认提供 |
| 状态值 | 名称 | 含义 | 费用说明 |
| CU001 | 等待清关 | 货物等待清关 | 默认提供 |
| CU002 | 清关中 | 货物正在清关流程中 | 默认提供 |
| CU003 | 已清关 | 货物已完成清关流程 | 默认提供 |
| CU004 | 清关异常 | 货物在清关过程中出现异常 | 默认提供 |
| JQ001 | 收件人拒签 | 收件人明确拒收 | 默认提供 |
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 method="post" name="" action=" http://poll.kuaidi100.com/poll/query.do "><input type="text" name=" customer " value="xxxxxxxxxxxx" /><input type="text" name="sign" value="adfjslfjhasdfwofnwofwoeueerf" ><input type="text" name="param" value="xxx" ></form>| 发起方: | 贵公司，即快递100的客户，又称“贵方”，下同 |
| 请求地址: | http://poll.kuaidi100.com/poll/query.do |
| 通信协议: | HTTP |
| 请求类型: | POST |
| 字符集: | utf-8 |
| 请求内容方式: | customer =公司编号 //我方分配给贵司的的公司编号sign=MD5(param+key+customer) //签名，用于验证身份，按param +key+customer的顺序进行MD5加密，不需要加上“+”号，如{"com":"yuantong","num":"500306190180","from":"广东省深圳市","to":"北京市朝阳区"}xxxxxxxxxxxxyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyparam={ "com":"yuantong", //查询的快递公司的编码，一律用小写字母，见3.3《快递公司编码》 "num":"12345678", //查询的快递单号，单号的最大长度是32个字符 "from":"广东深圳", //出发地城市 "to":"北京朝阳" , //目的地城市，到达目的地后会加大监控频率 " phone ":"******", //收、寄件人的电话号码（手机和固定电话均可，只能填写一个，顺丰单号必填，其他快递公司选填。如座机号码有分机号，分机号无需上传。）"resultv2":"1" //添加此字段表示开通行政区域解析功能,见3.1.2相关说明 |
3.1.2查询返回
（1）查询结果
| 返回格式 | 返回内容 |
| json | {message: "ok", /*消息体，请忽略*/state: "3", /*快递单当前签收状态，包括0在途，1揽收，2疑难，3签收，4退签，5派件，6退回等7个状态，详见章3.1.3 */status: "200", /*通讯状态，请忽略*/condition: "D01", /*请忽略*/ischeck: "1", /*请忽略*/com: "baishiwuliu", /*快递公司编码,一律用小写字母，见3.3《快递公司编码》*/nu: "211287338436", /*单号*/data: /*最新查询结果，全量，倒序（即时间最新的在最前）*/ [{time: "2016-11-06 14:11:00", /*时间，原始格式*/context: "天津市|签收|天津市【天津塘沽新港分部】，赵艳松代签15166926883 已签收", /*内容*/ftime: "2016-11-06 14:11:00", /*格式化后时间*/areaCode: null, /*本数据元对应的行政区域的编码, 只有实时查询接口中提交resultv2标记后才会出，见3.1.1 */areaName: null, /*本数据元对应的行政区域的名称, 只有实时查询接口中提交resultv2标记后才会出，见3.1.1*/status: "签收" /*本数据元对应的签收状态, 只有实时查询接口中提交resultv2标记后才会出，见3.1.1*/},{time: "2016-11-06 08:36:32", /*时间，原始格式*/context: "天津市|派件|天津市【天津塘沽新港分部】，【赵艳松/15166926883】正在派件", /*内容*/ftime: "2016-11-06 08:36:32",/*格式化后时间*/areaCode: "CN121616003000",/*本数据元对应的行政区域的编码, 只有实时查询接口中提交resultv2标记后才会出，见3.1.1 */areaName: "天津,滨海,滨海,新港",/*本数据元对应的行政区域的名称, 只有实时查询接口中提交resultv2标记后才会出，见3.1.1*/status: "派件"/*本数据元对应的签收状态, 只有实时查询接口中提交resultv2标记后才会出，见3.1.1*/},],num: "", /*请忽略*/routeInfo: { /*出发、目的及当前城市，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/from: {number: "CN4302", /*出发城市编码，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/name: "湖南,株洲市" /*出发城市名称，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/},cur: {number: "CN1216", /*当前城市编码，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/name: "天津,滨海" /*当前城市名称，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/},to: {number: "CN1216", /*目的城市编码，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/name: "天津,滨海" /*出发城市名称，只有实时查询接口中提交resultv2标记后才会出现，见3.1.1*/}}} |
（2）错误信息代码
| 返回格式 | 返回错误信息内容 |
| json | {"result":false, /*查询结果：false表示查询失败*/"returnCode":"500", /*失败的代号*/"message":"查询失败" /*失败内容表述*/} |
3.1.3运单签收状态服务说明
State值表示如下含义：| 状态值 | 名称 | 含义 | 费用说明 |
| 0 | 在途 | 快件处于运输过程中 | 默认提供 |
| 1 | 揽收 | 快件已由快递公司揽收 | 默认提供 |
| 2 | 疑难 | 快递100无法解析的状态，或者是需要人工介入的状态，比方说收件人电话错误。 | 默认提供 |
| 3 | 签收 | 正常签收 | 默认提供 |
| 4 | 退签 | 货物退回发货人并签收 | 默认提供 |
| 5 | 派件 | 货物正在进行派件 | 默认提供 |
| 6 | 退回 | 货物正处于返回发货人的途中 | 默认提供 |
| 10 | 待清关 | 货物等待清关 | 默认提供 |
| 11 | 清关中 | 货物正在清关流程中 | 默认提供 |
| 12 | 已清关 | 货物已完成清关流程 | 默认提供 |
| 13 | 清关异常 | 货物在清关过程中出现异常 | 默认提供 |
| 14 | 收件人拒签 | 收件人明确拒收 | 默认提供 |
3.2 查询接口并发协议
基于快递公司系统承压能力有限等原因，暂只能为贵司提供1单/秒的查询并发线程量，若贵司向我方的查询并发量超出约定额度，我方会报超并发错误，如下：超并发提示代码：| 返回格式 | 返回错误信息内容 |
| json | {"result":false, /*查询结果：false表示查询失败*/"returnCode":"502", /*超并发代号*/"message":"服务器繁忙" /*内容表述*/} |
3.3 快递公司编码
注：公司编码请严格使用小写字符如果您需要的公司不在此列表，请联系快递100业务联系人添加。**公司编码请严格使用小写字符见附件《快递100公司编码.xlsx》四、快递100单号归属公司智能判断接口
4.1 作用
将运单号通过我们接口提交至我方，我方返回该运单号可能对应的快递公司的列表。贵司可以用于提前判断用户或商家所输入的快递单号所归属的快递公司，以提升商家录入体验，或可用于对商家录入的信息进行提交较验，以减少商家的录入错误。4.2 费用与权利责任
由于运单号规则不断变化且各个快递公司没有标准、统一的规则，我们现有机制是通过我们积累的海量数据进行智能分析得出相关规则并且每天更新，所以我们无法保证判断准确率能达到100%。为此，本接口免费提供给贵司使用，同时，我方也不会对本接口的准确性、有效性等提供法律层面上的承诺。当然，本接口同时为我方官网所用接口，所以我方会尽力维护。若贵司将此服务向最终用户提供，建议贵司在展现给用户时加上如下提示：（1）判断结果后加上一句 “由快递100猜测”等带“猜测”字样的文字说明；（2）所选的公司可由用户重新手动修改；（3）在判断结果后提示“本结果仅供参考”等文字说明。4.3 单号归属公司智能判断接口的使用办法
4.3.1 请求地址与参数
http://www.kuaidi100.com/autonumber/auto?num=[单号]&key=[key]示范：http://www.kuaidi100.com/autonumber/auto?num=906919164534&key=XDSFDFDSF| 字段 | 说明 | 备注 |
| [单号] | 快递单号 | |
| [key] | 身份授权key |
4.3.2返回结果
| 字段 | 说明 | 备注 |
| comCode | 公司编码 | 快递公司对应的编码 |
| Id | （系统内部字段） | 请忽略 |
| noCount | （系统内部字段） | 请忽略 |
| noPre | （系统内部字段） | 请忽略 |
| startTime | （系统内部字段） | 请忽略 |
| [{"comCode":"shunfeng","id":"","noCount":302236,"noPre":"9069","startTime":""},{"comCode":"yuantong","id":"","noCount":24,"noPre":"9069","startTime":""}] |
更多相关文章
- [源码分析] 从实例和源码入手看 Flink 之广播 Broadcast
- [源码分析]从"UDF不应有状态" 切入来剖析Flink SQL代码生成 (修
- 从"UDF不应有状态" 切入来剖析Flink SQL代码生成
- 基于内阻增加和容量衰减双重标定的锂电池健康状态评估
- BlueStore源码分析之事物状态机
- 通过lua将nginx请求状态码转变为自定义状态码
- HTTP状态码及说明
- Spring Data开发手册｜Java持久化API（JPA）需要了解到什么程度呢？
- 【DB笔试面试702】在Oracle中，如何定时清理INACTIVE状态的会话？