快递100企业版物流快递查询接口（API） 接口文档-详细加长版

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

 

一、接口选用指南

接口	功能及性能一览	适用应用场景	计费方式
快递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便通过调用回调接口将运单的跟踪信息（又称“查询结果”下同）推送给贵公司，直到这些运单号的生命周期结束（一般以“已签收”为准）。

1. 订阅接口协议我方已定义好，直接按说明提交请求即可，详见下面2.2；

2. 回调接口需要由贵公司按我方协议来开发，协议详见下面2.3。

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.

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

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

3. 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:

200: 提交成功

701: 拒绝订阅的快递公司

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

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

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

601: POLL:KEY已过期

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