|
1.注册快递100账号，获取key和公司编号
注：快递100基础版不支持主流快递，如三通一达、顺丰、京东、EMS、德邦、天天、百世、邮政等主流快递的查询。企业版支持所有快递，且有100单的免费测试。
我注册的是企业版的。
注册成功后，从这里获取key和customer（公司编号）用于接口使用
可以查看接口信息，能使用那些功能，下图是企业版拥有的功能
我只是用到其中圈红的三个接口
2.接口使用简单讲解
（1）智能判断接口：输入一个正确的物流单号，可以智能的判断属于哪个快递公司的物流单号，获取相应快递公司的编码，用于实时查询接口和订阅推送接口
返回智能识别的结果可能有多个结果也可能没有结果，这边业务使用时需要判断一下
返回结果为多个时，我一般取第一个（可能性最大）
（2）实时查询接口：顾名思义，手动的去实时查询物流的最新动态
参数注意一下这几个必填的，还有查顺丰的单号时手机号必填，其他的看情况去设置参数即可
快递公司编码是智能识别出的公司编码，当然如果知道要查询的快递是哪个公司的快递，可以不使用智能识别接口
快递公司编码下载
返回结果：
对快递单号状态的解释：
我当前项目中没有对快递状态进行处理，只是展示快递的信息给用户
（3）订阅推送接口：跟项目结合的更紧密一点，通过订阅某个物流单号，当订阅的单号物流状态更新后，通过设定的回调地址异步的通知项目，这样就可以不必实时的请求快递100的实时查询物流接口
有好处也有不好的地方，需要自己去设计数据库，存储和展示，后期准备把项目改成这样，当然需要结合项目的业务逻辑去实现。
参数比较多：但是只需要看必需的参数和顺丰单号特殊处理手机号就行，其他参数是选填
订阅的快递公司编码是智能识别出的公司编码，当然如果知道要查询的快递是哪个公司的快递，可以不使用智能识别接口
快递公司编码下载
回调地址是你项目的回调地址，不要弄错了
返回信息中查看lastResult中的state:快递单号状态、ischeck:是否签收标记、data:物流信息数组，data里面有多个物流信息，第一个是最新的。
3.接口封装为类和回调处理
class Logistics
{
/**
* 客户授权key
* @var string
*/
protected $key = '';
/**
* 查询公司编号
* @var string
*/
protected $customer = '';
/**
* 智能判断快递公司编码
* @param $num
* @return array|mixed
*/
public function autoNumber($num)
{
if (empty($num)) return [];
//智能判断请求地址
$url = 'http://www.kuaidi100.com/autonumber/auto';
$post_data = array();
$post_data['key'] = $this->key;
$post_data['num'] = $num;
$params = $this->urlEncodeParam($post_data);
$result = $this->curlRequest($url, $params);
return $result[0] ?? [];
}
/**
* 订阅请求
* @param $num
* @return mixed
*/
public function subscribe($num)
{
//订阅请求地址
$url = 'http://poll.kuaidi100.com/poll';
$type = $this->autoNumber($num);
if (!isset($type['comCode']) || empty($type['comCode'])) return [];
//参数设置
$param = array(
'company' => $type['comCode'], //快递公司编码
'number' => $num, //快递单号
'from' => '', //出发地城市
'to' => '', //目的地城市
'key' => $this->key, //客户授权key
'parameters' => array(
'callbackurl' => 'http://www.solveset.net/api/logisticsNotify',//回调地址
'salt' => '', //加密串
'resultv2' => '1', //行政区域解析
'autoCom' => '0', //单号智能识别
'interCom' => '0', //开启国际版
'departureCountry' => '', //出发国
'departureCom' => '', //出发国快递公司编码
'destinationCountry' => '', //目的国
'destinationCom' => '', //目的国快递公司编码
'phone' => '' //手机号
)
);
//请求参数
$post_data = array();
$post_data['schema'] = 'json';
$post_data['param'] = json_encode($param);
$params = $this->urlEncodeParam($post_data);
return $this->curlRequest($url, $params);
}
/**
* 实时查询
* @param $num
* @return mixed
*/
public function nowQuery($num)
{
//实时查询请求地址
$url = 'http://poll.kuaidi100.com/poll/query.do';
$type = $this->autoNumber($num);
if (!isset($type['comCode']) || empty($type['comCode'])) return [];
//参数设置
$param = array(
'com' => $type['comCode'], //快递公司编码
'num' => $num, //快递单号
'phone' => '', //手机号
'from' => '', //出发地城市
'to' => '', //目的地城市
'resultv2' => '1' //开启行政区域解析
);
//请求参数
$post_data = array();
//查询公司编号
$post_data['customer'] = $this->customer;
$post_data['param'] = json_encode($param);
$sign = md5($post_data['param'] . $this->key . $post_data['customer']);
$post_data['sign'] = strtoupper($sign);
$params = $this->urlEncodeParam($post_data);
return $this->curlRequest($url, $params);
}
/**
* 对参数进行urlencode
* @param $data
* @return bool|string
*/
protected function urlEncodeParam($data)
{
$params = '';
foreach ($data as $k => $v) {
$params .= $k . '=' . urlencode($v) . '&';//默认UTF-8编码格式
}
$data = substr($params, 0, -1);
return $data;
}
/**
* curl请求
* @param $url
* @param $post_data
* @return mixed
*/
protected function curlRequest($url, $post_data)
{
$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);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($ch);
$data = str_replace("\"", '"', $result);
return json_decode($data, true);
}
}
调用：
$obj = new Logistics();
print_r($obj->nowQuery('123123'));
//print_r($obj->subscribe('123123'));
回调处理
路由：使用的是laravel框架
//物流订阅回调
Route::any('/api/logisticsNotify', 'Api\ApiTestController@logisticsNotify');
业务处理
//测试物流订阅回调
public function logisticsNotify()
{
$body = file_get_contents('php://input');
if (!empty($body)) {
//url解码
$body_str = urldecode($body);
$data_str = substr($body_str, strpos($body_str, 'param=') + 6);
if (!empty($data_str)) {
//json字符串转换为数组格式
$data = djson($data_str);
//处理逻辑
iF(!empty($data)) {
//快递单状态 0在途，1揽收，2疑难，3签收，4退签，5派件，6退回
if($data['lastResult']['state'] == 3) {
//订单状态修改为已收货
}
}
//记录日志
$filePath = createLogFile('logisticsNotify.log', 'logs/solve');
file_put_contents($filePath, '物流单号异步通知：' . var_export($data, true), FILE_APPEND);
}
}
//返回成功状态
echo json(['result' => true, 'returnCode' => 200, 'message' => '成功']);
}
日志中的记录
到目前为止，只是简单的解释了三个接口，写了一个demo，但是大概思路和流程是完善的，是对项目使用快递100的一个整理和备忘。
|