顺丰开放平台Api PHP SDK demo
引用
对接前期工作注册
提交接入申请
接口初始化配置，获得 app_id 和app_secret
完成测试环境测试
进入生产使用
接入注意事项申请令牌 (/security/access_token/ 接口)
access_token 有效期为 1 小时，过期需使用 refresh_token 刷新令牌(/security/refresh_token/ 接口)
refresh_token 有效期为当天 24 点，过期需重新申请(/security/access_token/ 接口)
接口均为 https ，数据传输格式为 json
Demo
SDK Demo<?php
/**
* 顺丰 api 接口使用
* Date: /10/19
* Time: 9:36
* @author zlh
*/
class SfApi {
/**
* @var string
*/
protected $app_id;
/**
* @var string
*/
protected $app_key;
/**
* @var string
*/
public $access_token;
/**
* @var string
*/
public $refresh_token;
/**
* @var string
*/
private $uri;
/**
* SfApi constructor.
* @param string $app_id
* @param string $app_key
* @param bool $online
* @return void
*/
public function __construct ($app_id, $app_key, $online = false) {
$this->app_id = $app_id;
$this->app_key = $app_key;
$this->url = $online ? 'https://open-prod.sf-/' : 'https://open-sbox.sf-/';
}
/**
* 快速创建订单
* @param array $req_body
* @return bool|string
*/
public function order ($req_body) {
$req_body = array(
'orderId' => $req_body['orderId'],
'expressType' => $req_body['expressType'],
'payMethod' => $req_body['payMethod'],
'custId' => $req_body['custId'],
'payArea' => isset($req_body['payArea']) ? $req_body['payArea'] : 'SFCM10008035754399',
//'remark' => $req_body['remark'],
'consigneeInfo' => array(
'company' => isset($req_body['consigneeInfo']['company']) ? $req_body['consigneeInfo']['company'] : '个人',
'contact' => $req_body['consigneeInfo']['contact'],
'tel' => $req_body['consigneeInfo']['tel'],
'province' => $req_body['consigneeInfo']['province'],
'city' => $req_body['consigneeInfo']['city'],
'county' => $req_body['consigneeInfo']['county'],
'address' => $req_body['consigneeInfo']['address'],
'mobile' => $req_body['consigneeInfo']['mobile'],
),
'cargoInfo' => array(
'cargo' => $req_body['cargoInfo']['cargo'],
),
'addedServices' => $req_body['addedServices'],
);
$res = $this->send('order', $req_body);
$res_tmp = json_decode($res, true);
if(empty($res_tmp['head']['code'])) {
return '系统错误！';
}elseif(substr($res_tmp['head']['code'], -3) != '200') {
return $res_tmp['head']['message'];
}else{
return true;
}
}
/**
* 订单结果查询
* @param string $order_id
* @return json
*/
public function orderQuery ($order_id) {
$req_body = array(
'orderId' => $order_id
);
return $this->send('order/query', $req_body);
}
/**
* 根据 运单号/订单号 查询物流路由
* @param array $req_body
* @return json
*/
public function routeQuery ($req_body) {
$req_body = array(
'trackingType' => $req_body['trackingType'],
'trackingNumber' => $req_body['trackingNumber'],
'methodType' => $req_body['methodType'],
);
return $this->send('route/query', $req_body);
}
/**
* 电子运单图片下载
* @param string $orderId
* @param bool $isLogo
* @return json (image参数为BASE64编码的字符串)
*/
public function wayBillImage ($orderId, $isLogo = false) {
$req_body = array(
'orderId' => $orderId,
'isLogo' => $isLogo ? 1 : 0
);
return $this->send('waybill/image', $req_body);
}
/**
* 获取顺丰授权
* @return json
*/
public function getToken () {
return $this->send('security/access_token');
}
/**
* 刷新授权令牌
* @param string $access_token
* @param string $refresh_token
* @return json
*/
public function refreshToken ($access_token, $refresh_token) {
$this->access_token = $access_token;
$this->refresh_token = $refresh_token;
return $this->send('security/refresh_token');
}
/**
* 忘记 access_token 查询
* @return json
*/
public function queryToken () {
return $this->send('security/access_token/query');
}
/**
* 根据请求的接口创建相应的 Uri
* @param string $resource 要请求的resource(前后不带'/')
* @return string
*/
protected function buildUri ($resource) {
$query = '/sf_appid/' . $this->app_id . '/sf_appkey/' . $this->app_key;
if ($resource == 'security/refresh_token') {
$query = "/access_token/$this->access_token/refresh_token/$this->refresh_token" . $query;
}elseif (substr($resource, 0, 8) != 'security') {
$query = '/access_token/' . $this->access_token . $query;
}
$uri = $this->url . $this->transType()[$resource]['type'] . '/v1.0/' . $resource . $query;
return $uri;
}
/**
* 向顺丰接口发送请求
* SSL POST JSON
* @param string $resource 要请求的resource(前后不带'/')
* @param array $body 请求报文(参数)
* @return json
*/
protected function send ($resource, $body = array()) {
$this->uri = $this->buildUri($resource);
$req_data = array(
'head' => array(
'transType' => $this->transType()[$resource]['transType'],
'transMessageId' => date('Ymd') . substr_replace(time(), mt_rand(10,99),0,2),
)
);
if(!empty($body)) {
$req_data['body'] = $body;
}
$header = array(
"Content-Type: application/json",
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->uri);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 跳过证书检查
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, true); // 从证书中检查SSL加密算法是否存在
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($req_data));
$response = curl_exec($ch);
curl_close($ch);
return $response;
}
/**
* 顺丰开放平台各接口对应的资源类型
* @return array
*/
private function transType () {
return array(
'order' => array('transType' => 200, 'type' => 'rest'),
'order/query' => array('transType' => 203, 'type' => 'rest'),
'filter' => array('transType' => 204, 'type' => 'rest'),
'route/query' => array('transType' => 501, 'type' => 'rest'),
'route/inc/query' => array('transType' => 504, 'type' => 'rest'),
'waybill/image' => array('transType' => 205, 'type' => 'rest'),
'product/basic/query' => array('transType' => 250, 'type' => 'rest'),
'product/additional/query' => array('transType' => 251, 'type' => 'rest'),
'security/access_token/query' => array('transType' => 300, 'type' => 'public'),
'security/access_token' => array('transType' => 301, 'type' => 'public'),
'security/refresh_token' => array('transType' => 302, 'type' => 'public'),
);
/**
快速下单 /order/ 200
订单查询 /order/query/ 203
订单筛选 /filter/ 204
路由查询 /route/query/ 501
路由增量查询 /route/inc/query/ 504
电子运单图片下载 /waybill/image/ 205
基础服务查询 /product/basic/query/ 250
附加服务查询 /product/additional/query/ 251
申请访问令牌 /security/access_token/ 301
查询访问令牌 /security/access_token/query/ 300
刷新访问令牌 /security/refresh_token/ 302
*/
}
}
使用引入该类文件
并实例化，参数分别为 app_id, app_secret, 是否用于生产环节 (true|false),默认为 false。
检查 access_token 并设置。
调用对应方法即可，详细使用请参考方法注释和顺丰接口文档。
例子// 实例化对象并传入参数
$sf = new SfApi('your app_id', 'your app_secret', false);
// 获取 access_token
$token_res = $sf->getToken();
var_dump($token_res);
// 为对象设置 access_token 属性
$sf->access_token = json_decode($token_res, true)['body']['accessToken'];
// 下单
$req_body = array(
'orderId' => 'SF10091507536283',
'expressType' => 1,
'payMethod' => 3,
'custId' => 'your custId',
'payArea' => '010EU',
'remark' => '备注',
'consigneeInfo' => array(
'company' => '个人',
'contact' => '测试对象',
'tel' => '17600000000',
'province' => '北京市',
'city' => '北京市',
'county' => '朝阳区',
'address' => '十里河',
'mobile' => '17600000000',
),
'cargoInfo' => array(
'cargo' => '产品名',
),
// 代收货款需填，标准快递则不需要如下参数
'addedServices' => array(
array(
'name' => 'COD',
'value' => '698',
),
array(
'name' => 'CUSTID',
'value' => 'your custId'
)
)
);
$order_res= $sf->order($req_body);
var_dump($order_res);
// 获取运单图片
$image_res = $sf->wayBillImage('SF10091507536283');
$image_res = json_decode($image_res, true);
file_put_contents('./SF10091507536283.jpg', base64_decode($image_res['body']['images'][0]));
echo '';
运单图片
示例
图中马赛克为手打
运单图片处理
处理图片使用 GD 或 imagemagick 等处理图片的库。
一般来说需要隐藏客户的收件信息，下附上图片处理相关函数。/** 图片局部打马赛克
* @param String $source 原图
* @param Stirng $dest 生成的图片
* @param int $x1 起点横坐标
* @param int $y1 起点纵坐标
* @param int $x2 终点横坐标
* @param int $y2 终点纵坐标
* @param int $deep 深度，数字越大越模糊
* @param bool $fill 是否只填充白色
* @return boolean
*/
function imageMosaics($source, $dest, $x1, $y1, $x2, $y2, $deep, $fill = false){
// 判断原图是否存在
if(!file_exists($source)){
return false;
}
// 获取原图信息
list($owidth, $oheight, $otype) = getimagesize($source);
// 判断区域是否超出图片
if($x1>$owidth || $x1<0 || $x2>$owidth || $x2<0 || $y1>$oheight || $y1<0 || $y2>$oheight || $y2<0){
return false;
}
switch($otype){
case 1: $source_img = imagecreatefromgif($source); break;
case 2: $source_img = imagecreatefromjpeg($source); break;
case 3: $source_img = imagecreatefrompng($source); break;
default:
return false;
}
// 打马赛克
if($fill === false) {
for($x=$x1; $x
for($y=$y1; $y
$color = imagecolorat($source_img, $x+round($deep/2), $y+round($deep/2));
imagefilledrectangle($source_img, $x, $y, $x+$deep, $y+$deep, $color);
}
}
}else{
$im = imagecreatetruecolor(200, 200);
$fill = imagecolorallocate($im, 255, 255, 255);
imagefilledrectangle($source_img, $x1, $y1, $x2, $y2, $fill);
}
// 生成图片
switch($otype){
case 1: imagegif($source_img, $dest); break;
case 2: imagejpeg($source_img, $dest); break;
case 3: imagepng($source_img, $dest); break;
}
return is_file($dest)? true : false;
}// 使用
$source = $dest = './10244108826825.jpg';
// 5,5 1125,100 区域填充白色(应对带有顺丰logo的打印纸)
$flag = imageMosaics($source, $dest, 5, 5, 1125, 100, 4, true);
// (120)215, 250 810,400 区域马赛克
$flag = imageMosaics($source, $dest, 215, 250, 810, 400, 7);
// (110)210,1207 678,1314 区域马赛克
$flag = imageMosaics($source, $dest, 210, 1207, 678, 1314, 7);
echo '';该函数为以前网络上找到并改造的，未找到原作者。如有侵权请联系我删除。
处理后示例
图中 logo 处和收件人处为函数生成的马赛克、填充白色，其余区域为手打马赛克。
其他
代码写的比较仓促，不过一般的与顺丰对接也就这些基本功能，还有一些接口本文没有用到的，可以参考上面 SDK 中对应函数的注释和接口文档。
注：转载请注明出处。
本文由 root 创作，采用 知识共享署名4.0 国际许可协议进行许可
本站文章除注明转载/出处外，均为本站原创或翻译，转载前请务必署名
最后编辑时间为: Sep 28, at 12:10 pm
