订阅推送API

  • 简介:快递100信息推送服务是快递100 针对有超大运单查询需求的企业推出的一项增值服务,服务整个过程是:贵公司将需要跟踪的运单提交给快递100指定的接口,快递100接到后就对这些单号进行监控,如果监控到运单有了更新,就主动将这些物流跟踪信息推送到贵公司指定的接口,直到这些单的生命周期结束(一般以“已签收”为准),一个运单快递100一般会多次推送多条跟踪信息,贵方将之保存到数据库。当用户登录贵方网站、系统或手机APP时,直接从贵司的数据库读取数据,并显示于贵方的网站、系统或手机APP。
1、应用场景
(1)让顾客登录您的网站后,直接在“我的订单”页面内就能看到订单的物流状态。
(2)能开发自动的、批量查单功能,自动筛选出“已签收”、“疑难件”等状态的单号,减轻跟单人员的压力。
(3)改变订单的状态与交易流程,例如只要运单号变为“已签收”,就能让订单变为可以确认退换货等。
(4)核销售人员,评估与选择快递公司,根据“已签收”的运单数,就能算出销售人员的业绩。
(5)助结算运费,用API找出“已签收”的单及签收时间,便能轻松应对货到付款的结算与对帐。
2、是否需要授权
是,请到 快递查询API申请地址 申请
3、系统结构与流程

4、订阅接口协议

4.1、订阅请求地址
正式环境请求地址:https://poll.kuaidi100.com/poll
4.2、订阅请求类型
post

4.3、订阅输入参数

名称 类型 是否必需 示例值   描述
schema String JSON 返回的数据格式
param Object 由其他字段拼接
 └ company String ems 订阅的快递公司的编码,一律用小写字母
 └ number String em263999513jp 订阅的快递单号,单号的最大长度是32个字符
 └ from String 广东省深圳市南山区 出发地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,请尽量提供
 └ to String 北京市朝阳区 目的地城市,省-市-区,非必填,填了有助于提升签收状态的判断的准确率,且到达目的地后会加大监控频率,请尽量提供
 └ key String 授权码,签合同后发放,详请联系 快递100 对接人 www.kuaidi100.com/openapi, 请参考邮件《快递100-企业版快递查询接口(API)——授权key及相关工具》
 └ parameters Object 附加参数信息
  └- callbackurl String http://www.您的域名.com/kuaidi?callbackid=... 回调接口的地址
  └- salt String XXXXXXXXXX 签名用随机字符串
  └- resultv2 String 1 添加此字段表示开通行政区域解析功能(仅对开通签收状态服务用户有效)
  └- autoCom String 1 添加此字段且将此值设为1,则表示开始智能判断单号所属公司的功能,开启后,company字段可为空,即只传运单号(number字段),我方收到后会根据单号判断出其所属的快递公司(即company字段)。建议只有在无法知道单号对应的快递公司(即company的值)的情况下才开启此功能
  └- interCom String 1 添加此字段表示开启国际版,开启后,若订阅的单号(即number字段)属于国际单号,会返回出发国与目的国两个国家的跟踪信息,本功能暂时只支持邮政体系(国际类的邮政小包、EMS)内的快递公司,若单号我方识别为非国际单,即使添加本字段,也不会返回destResult元素组
  └- departureCountry String CN 出发国家编码
  └- departureCom String ems 出发的快递公司的编码
  └- destinationCountry String JP 目的国家编码
  └- destinationCom String japanposten 目的的快递公司的编码

4.4、订阅请求参数示例

    schema= json
    param={
        "company":"ems",
        "number":"em263999513jp",
        "from":"广东省深圳市南山区",
        "to":"北京市朝阳区",
        "key":"XXX ",
        "parameters":{
            "callbackurl":"您的回调接口的地址,如http://www.您的域名.com/kuaidi?callbackid=...",
            "salt":"XXXXXXXXXX",
            "resultv2":"1",
            "autoCom":"1",
            "interCom":"1",
            "departureCountry":"CN",
            "departureCom":"ems",
            "destinationCountry":"JP",
            "destinationCom":"japanposten"
        }
    }
         

4.5、订阅返回结果

字段名称   字段含义
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后隔半小时再提交订阅
status 通讯状态,请忽略
condition 快递单明细状态标记,暂未实现,请忽略
ischeck 是否签收标记,请忽略,明细状态请参考state字段
com 快递公司编码,一律用小写字母
nu 单号
data 最新查询结果,数组,包含多项,全量,倒序(即时间最新的在最前),每项都是对象,对象包含字段请展开
 └ context 内容
 └ time 时间,原始格式
 └ ftime 格式化后时间

4.6、订阅返回示例(JSON格式)

    {
        "result":true,
        "returnCode":"200",
        "message":"提交成功"
    }
         

4.7、订阅代码示例

<?
    $post_data = array();
    $post_data["schema"] = 'json' ;

    //callbackurl请参考callback.php实现,key经常会变,请与快递100联系获取最新key
    $post_data["param"]='{"company":"yuantong", "number":"12345678","from":"广东深圳", "to":"北京朝阳",';
    $post_data["param"]=$post_data["param"].'"key":"testkuaidi1031",';
    $post_data["param"]=$post_data["param"].'"parameters":{"callbackurl":"http://www.yourdmain.com/kuaidi"}}';

    $url='http://www.kuaidi100.com/poll';

    $o="";
    foreach ($post_data as $k=>$v)
    {
        $o.= "$k=".urlencode($v)."&";		//默认UTF-8编码格式
    }

    $post_data=substr($o,0,-1);

    $ch = curl_init();
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_URL,$url);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    $result = curl_exec($ch);		//返回提交结果,格式与指定的格式一致(result=true代表成功)

?>

5、推送接口协议

5.1、推送请求地址
由贵司在订阅请求中通过callbackurl字段提供
5.2、推送请求类型
post

5.3、推送输入参数

名称 类型 示例值   描述
param Object 由其他字段拼接
 └ status String polling 监控状态:polling:监控中,shutdown:结束,abort:中止,updateall:重新推送。其中当快递单为已签收时status=shutdown,当message为“3天查询无记录”或“60天无变化时”status= abort ,对于stuatus=abort的状度,需要增加额外的处理逻辑
 └ billstatus String got 包括got、sending、check三个状态,由于意义不大,已弃用,请忽略
 └ message String 监控状态相关消息,如:3天查询无记录,60天无变化
 └ autoCheck String 1 快递公司编码是否出错,0为本推送信息对应的是贵司提交的原始快递公司编码,1为本推送信息对应的是我方纠正后的新的快递公司编码。一个单如果我们连续3天都查不到结果,我方会(1)判断一次贵司提交的快递公司编码是否正确,如果正确,给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=0、comOld与comNew都为空;(2)如果贵司提交的快递公司编码出错,我们会帮忙用正确的快递公司编码+原来的运单号重新提交订阅并开启监控(后续如果监控到单号有更新就给贵司的回调接口(callbackurl)推送带有如下字段的信息:autoCheck=1、comOld=原来的公司编码、comNew=新的公司编码);并且给贵方的回调接口(callbackurl)推送一条含有如下字段的信息:status=abort、autoCheck=0、comOld为空、comNew=纠正后的快递公司编码。
 └ comOld String yuantong 贵司提交的原始的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
 └ comNew String ems 我司纠正后的新的快递公司编码。详细见autoCheck后说明。若开启了国际版(即在订阅请求中增加字段interCom=1),则回调请求中暂无此字段
 └ lastResult Object 最新查询结果,若在订阅报文中通过interCom字段开通了国际版,则此lastResult表示出发国的查询结果,全量,倒序(即时间最新的在最前)
  └- message String 消息体,请忽略
  └- state String 0 快递单当前签收状态,包括0在途中、1已揽收、2疑难、3已签收、4退签、5同城派送中、6退回、7转单等7个状态,其中4-7需要另外开通才有效
  └- status String 200 通讯状态,请忽略
  └- condition String F00 快递单明细状态标记,暂未实现,请忽略
  └- ischeck String 0 是否签收标记
  └- com String yuantong 快递公司编码,一律用小写字母
  └- nu String V030344422 单号
  └- data Object 数组,包含多个对象,每个对象字段如展开所示
   └-- context String 上海分拨中心/装件入车扫描 内容
   └-- time String 2012-08-28 16:33:19 时间,原始格式
   └-- ftime String 2012-08-28 16:33:19 格式化后时间
   └-- status String 在途 本数据元对应的签收状态。只有在开通签收状态服务(见上面"status"后的说明)且在订阅接口中提交resultv2标记后才会出现
   └-- areaCode String 310000000000 本数据元对应的行政区域的编码,只有在开通签收状态服务(见上面"status"后的说明)且在订阅接口中提交resultv2标记后才会出现
   └-- areaName String 上海市 本数据元对应的行政区域的名称,开通签收状态服务(见上面"status"后的说明)且在订阅接口中提交resultv2标记后才会出现
 └ destResult Object 表示最新的目的国家的查询结果,只有在订阅报文中通过interCom=1字段开通了国际版才会显示此数据元,全量,倒序(即时间最新的在最前)
  └- message String 消息体,请忽略
  └- state String 0 快递单当前签收状态,包括0在途中、1已揽收、2疑难、3已签收、4退签、5同城派送中、6退回、7转单等7个状态,其中4-7需要另外开通才有效
  └- status String 200 通讯状态,请忽略
  └- condition String F00 快递单明细状态标记,暂未实现,请忽略
  └- ischeck String 0 是否签收标记
  └- com String yuantong 快递公司编码,一律用小写字母
  └- nu String V030344422 单号
  └- data Object 数组,包含多个对象,每个对象字段如展开所示
   └-- context String 上海分拨中心/装件入车扫描 内容
   └-- time String 2012-08-28 16:33:19 时间,原始格式
   └-- ftime String 2012-08-28 16:33:19 格式化后时间
   └-- status String 在途 本数据元对应的签收状态。只有在开通签收状态服务(见上面"status"后的说明)且在订阅接口中提交resultv2标记后才会出现
   └-- areaCode String 310000000000 本数据元对应的行政区域的编码,只有在开通签收状态服务(见上面"status"后的说明)且在订阅接口中提交resultv2标记后才会出现
   └-- areaName String 上海市 本数据元对应的行政区域的名称,开通签收状态服务(见上面"status"后的说明)且在订阅接口中提交resultv2标记后才会出现

5.4、推送输入参数示例

    param={
        "status":"polling",
        "billstatus":"got",
        "message":"",
        "autoCheck":"1",
        "comOld":"yuantong",
        "comNew":"ems",
        "lastResult":{
            "message":"ok",
            "state":"0",
            "status":"200",
            "condition":"F00",
            "ischeck":"0",
            "com":"yuantong",
            "nu":"V030344422",
            "data":[{
                "context":"上海分拨中心/装件入车扫描 ",
                "time":"2012-08-28 16:33:19",
                "ftime":"2012-08-28 16:33:19",
                "status":"在途",
                "areaCode":"310000000000",
                "areaName":"上海市",
            },
                "context":"上海分拨中心/下车扫描 ",
                "time":"2012-08-27 23:22:42",
                "ftime":"2012-08-27 23:22:42",
                "status":"在途",
                "areaCode":"310000000000",
                "areaName":"上海市",

             }]
	    },
        "destResult":{
            "message":"ok",
            "state":"0",
            "status":"200",
            "condition":"F00",
            "ischeck":"0"     ,
            "com":"speedpost",
            "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":"签收",
                "areaCode":null,
                "areaName":null,
            }]
        }
    }
         

5.5、推送返回结果

字段名称   字段含义
result true表示成功,false表示失败。如果提交回调接口的地址失败,30分钟后重新回调,3次仍旧失败的,自动放弃
returnCode 200: 提交成功
500: 服务器错误
其他错误请自行定义
message 返回的提示

5.6、推送返回示例(JSON格式)

    {
        "result":true,
        "returnCode":"200",
        "message":"成功"
    }
         

5.7、推送代码示例

<?php header("Content-Type:text/html;charset=utf-8"); ?>
<?
	//订阅成功后,收到首次推送信息是在5~10分钟之间,在能被5分钟整除的时间点上,0分..5分..10分..15分....
	$param=$_POST['param'];

	try{
		//$param包含了文档指定的信息,...这里保存您的快递信息,$param的格式与订阅时指定的格式一致

		echo  '{"result":"true",	"returnCode":"200","message":"成功"}';
		//要返回成功(格式与订阅时指定的格式一致),不返回成功就代表失败,没有这个30分钟以后会重推
	} catch(Exception $e)
		{
		echo  '{"result":"false",	"returnCode":"500","message":"失败"}';
		//保存失败,返回失败信息,30分钟以后会重推
	}


?>