JAVA 接入丰桥，下单到打印面单到配送开发流程

大家好，欢迎来到IT知识分享网。

顺丰开放平台地址：顺丰开放平台

一、了解官网 

        1.1、开发文档

开发接口之前可以先查看熟悉文档，尤其是API文档仔细阅读。进入之后是如下图，根据自己需要开发的接口，先查看文档，然后根据文档要求来请求并处理响应。

         1.2、服务接口

 点击开发者对接，进入之后，点击开发者对接，再点击新建应用，根据要求填写信息。

 创建成功之后，会在下面展示你创建的应用。

 关联API，创建的时候可以关联API，创建之后也可以在查看API里面进行关联。

点击查看API进入

 然后点击关联API

 关联你想要的API

关联之后才可以联调测试上线！

二、 SDK使用

2.1、查看官网SDK

点击控制台，找到开发规范点进去。

 找到 API-SDK使用说明

 官网的是拿java举例是哟SDK的，这里我们也是用跟java做集成的SDK

点击SDK工具，然后选择JAVA的 ，点击下载最新版就可以了（也可以查看版本下载其他的版本）

下载之后是一个zip压缩包，解压之后，我们需要下面标红的这三个部分。

code：是一些枚举类，可以不用，因为SF-CSIM-EXPRESS-SDK-V2.1.7.jar里面包含了。

java-demo：是测试类，这个我们需要将他拷贝到我们的项目里，然后封装成一个工具类。

json：这里面是请求API接口的一些请求参数示例，这个可要可不要。

lib：这个是需要的其他依赖包。

readme.txt：无关紧要的东西吧。

SF-CSIM-EXPRESS-SDK-V2.1.7.jar：这个是核心包，顺丰封装的jar包。

2.2、集成到项目

        2.2.1、添加依赖（这里我用的是maven管理依赖的方式）

<!--顺丰依赖--> <dependency> <groupId>commons-codec</groupId> <artifactId>commons-codec</artifactId> <version>1.9</version> </dependency> <dependency> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> <version>1.2</version> </dependency> <dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> <version>4.3.2</version> </dependency> <dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpcore</artifactId> <version>4.3.2</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>1.7.7</version> </dependency> <!--顺丰的核心包（本地打包）--> <dependency> <groupId>com.sf.csim.express</groupId> <artifactId>SF-CSIM-EXPRESS-SDF</artifactId> <version>V2.1.7</version> </dependency>

注意顺丰的核心包maven官网是不提供的，需要我们自己将下载的SF-CSIM-EXPRESS-SDK-V2.1.7.jar包打到我们maven的本地仓库（这里不过多解释，主要针对集成顺丰）。其他的依赖包maven远程仓库都是可以下载的。

        2.2.2、配置应用信息

配置应用信息，下一步封装工具类需要。

        2.2.3、封装工具类

package com.casic.cloud.webtrans.utils; import com.sf.csim.express.service.CallExpressServiceTools; import com.sf.csim.express.service.HttpClientUtil; import org.apache.commons.lang.StringUtils; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import java.util.HashMap; import java.util.Map; import java.util.UUID; / * 20 ^O^开心快乐!!! * * @Description: CallExpressNewAPIServiceUtil类...，调用顺丰API * @Author: Wuxinke * @Date: 2023/3/20 / @Component public class CallExpressNewAPIServiceUtil { //此处替换为您在丰桥平台获取的顾客编码 @Value("${CLIENT_CODE}") private String CLIENT_CODE; //此处替换为您在丰桥平台获取的校验码 @Value("${CHECK_WORD}") private String CHECK_WORD; //沙箱环境的地址 -PRO @Value("${CALL_URL_BOX}") private String CALL_URL_BOX; //生产环境的地址 -PRO @Value("${CALL_URL_PROD}") private String CALL_URL_PROD; / *@Description: 调用顺丰API方法 * msgData：请求报文 serviceCode:接口服务码 *@Date: 2023/3/20 17:25 / public String callSFApi(String serviceCode,String msgData) throws Exception { //验证请求参数 if(StringUtils.isEmpty(serviceCode) || StringUtils.isEmpty(msgData)){ throw new Exception("参数不能为空!"); } CallExpressServiceTools tools=CallExpressServiceTools.getInstance(); // set common header Map<String, String> params = new HashMap<String, String>(); String timeStamp = String.valueOf(System.currentTimeMillis()); params.put("partnerID", CLIENT_CODE); // 顾客编码 ，对应丰桥上获取的clientCode params.put("requestID", UUID.randomUUID().toString().replace("-", ""));//请求唯一号UUID params.put("serviceCode",serviceCode);// 接口服务码 params.put("timestamp", timeStamp);//调用接口时间戳 params.put("msgData", msgData);//报文 params.put("msgDigest", tools.getMsgDigest(msgData,timeStamp,CHECK_WORD));//数字签名 long startTime = System.currentTimeMillis(); System.out.println("====调用实际请求：" + params); String result = HttpClientUtil.post(CALL_URL_BOX, params); System.out.println("====调用丰桥的接口服务代码：" + String.valueOf(serviceCode) + " 接口耗时："+ String.valueOf(System.currentTimeMillis()-startTime)+"===="); System.out.println("===调用地址 ==="+CALL_URL_BOX); System.out.println("===顾客编码 ==="+CLIENT_CODE); System.out.println("===返回结果：" +result); return result; } } 

到这一步就算集成成功了，接下来就是去具体的操作某些接口。

三、集成顺丰的常用API

3.1、下订单接口

接口代码：

public ApiResultModel placeOrder(@RequestBody MsgData msgData,HttpServletRequest request){ try{         //快件产品类别 msgData.setExpressTypeId(2);         //是否返回路由标签： 默认1， 1：返回路由标签， 0：不返回 msgData.setIsReturnRoutelabel(1);         //响应报文的语言 msgData.setLanguage("zh-CN");         //客户订单号，不能重复 msgData.setOrderId("OrderNum"+UUID.randomUUID().toString()); //物品信息 List<TransCargodetail> cargoDetails = msgData.getCargoDetails(); if(cargoDetails == null || cargoDetails.size() <= 0){ return $.error("请添加物品"); } for (TransCargodetail cargoDetail : cargoDetails) { cargoDetail.setCurrency(currency);//币别 cargoDetail.setAmount(amount);//货物单价 } //寄收信息 List<TransContactinfo> contactInfos = msgData.getContactInfoList(); if(contactInfos == null || contactInfos.size() != 2){ return $.error("寄收件信息缺失"); }         //解析为json格式的字符 String jsonObject = JSONObject.toJSONString(msgData);         //下单 String result = callExpressNewAPIServiceUtil .callSFApi(ExpressServiceCodeEnum.EXP_RECE_CREATE_ORDER.getCode(), jsonObject); //处理响应数据，根据自己的系统业务逻辑保存下单相应的数据         .... }catch (Exception e){ e.printStackTrace(); return $.error(e.getMessage()); } } 

 请求参数：

{

“cargoDetails”:[

    {

        “count”:1,

        “unit”:”个”,

        “weight”:1.2,

        “name”:”护肤品1″

    }

],

“contactInfoList”:[

    {

        “address”:”广东省深圳市南山区软件产业基地11栋-222″,

        “userCguid”:”916″,

        “contact”:”小曾”,

        “corporation”:”航天重型工程装备有限公司”,

        “contactType”:1,

        “country”:”CN”,

        “postCode”:””,

        “tel”:””,

        “province”:”广东省”,

        “city”:”深圳市”,

        “county”:”南山区”

    },

    {

        “address”:”广东省广州市白云区湖北大厦-222″,

        “company”:”顺丰速运”,

        “userCguid”:”100″,

        “contact”:”小邱”,

        “corporation”:”航天重型工程装备有限公司”,

        “contactType”:2,

        “country”:”CN”,

        “postCode”:””,

        “tel”:””,

        “province”:”广东省”,

        “city”:”广州市”,

        “county”:”白云区”

    }

],

“cooperateSchemaId”:”52fdab34ba9e380″,

“paymoneyWay”:1,

“transCorporationCguid”:”25dsadsadasdsadsa2322″,

“transCorporation”:”顺丰速运”,

“monthlyCguid”:”48dsadsdef97f8sd7d87sahd67sdhus8d78sd”,

“monthlyAccount”:”admin123″,

“weight”:12.3,

“volume”:20.4,

“count”:2

}

//cargoDetails：物品集合

       // “count”:数量

       // “unit”:单位

       // “weight”:重量

       // “name”:”护肤品1″

       

//contactInfoList：寄收件信息

       // “address”:详细地址

       // “userCguid”:用户主键

       // “contact”:姓名

       // “corporation”:公司名称

       // “contactType”:地址类型： 1，寄件方信息 2，到件方信息

       // “tel”:电话

       // “province”:所在省级行政区名称,

       // “city”:所在地级行政区名称,

       // “county”:所在县/区级行政区名称

//cooperateSchemaId :订单主键

//paymoneyWay:支付方式 1：寄付  2：到付  3：月结

//transCorporationCguid:物流公司主键

//transCorporation:物流公司

//monthlyCguid:月结账号主键

//monthlyAccount:月结账号

//weight:总重量

//volume：总体积

//count:总数量

3.2、时效标准及价格查询接口

接口代码：

public ApiResultModel queryPrice(@RequestBody MsgData msgData,HttpServletRequest request){ try{         //快件产品 msgData.setBusinessType("2"); SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"); Date date = new Date();         //下单时间 msgData.setConsignedTime(simpleDateFormat.format(date));         //查询价格 msgData.setSearchPrice("1"); //物品 List<TransCargodetail> cargoDetails = msgData.getCargoDetails(); //总重量 Long weight = 0l; //总体积 Long volume = 0l; //总数量 int count = 0; for (TransCargodetail cargoDetail : cargoDetails) { //重量 Long weightCell = cargoDetail.getWeight()*cargoDetail.getCount(); //体积 Long volumeCell = cargoDetail.getLength()*cargoDetail.getWidth()*cargoDetail.getHeight()*cargoDetail.getCount(); //数量 count+=cargoDetail.getCount(); weight+=weightCell; volume+=volumeCell; } msgData.setWeight(weight); msgData.setVolume(volume);         //解析为json格式的字符串 String msgDataJson = JSONObject.toJSONString(msgData); //时效标准及价格查询接口 String result = callExpressNewAPIServiceUtil .callSFApi(ExpressServiceCodeEnum.EXP_RECE_QUERY_DELIVERTM.getCode(), msgDataJson);         //处理响应数据，根据自己的系统业务逻辑保存下单相应的数据 }catch (Exception e){ e.printStackTrace(); return $.error(); } }

请求参数：

{

“destAddress”:{

        “address”:”北京街道西湖路38号首层102号东南铺江博士”,

        “city”:”广州市”,

        “district”:”越秀区”,

        “province”:”广东省”

},

“srcAddress”:{

        “address”:”琶洲街道琶洲蟠龙新街2号保利广场购物中心3层3036号江博士专卖铺”,

        “city”:”广州市”,

        “district”:”海珠区”,

        “province”:”广东省”

},

“cargoDetails”:[

        {

                “name”:”水杯”,

                “count”:1,

                “weight”:0.6,

                “length”:12,

                “width”:4,

                “height”:14

        },

        {

                “name”:”屏幕”,

                “count”:1,

                “weight”:1.5,

                “length”:70,

                “width”:40,

                “height”:30

        }

]

}

//”destAddress”:{ :目的地信息

//    “address”:详细地址,

//    “city”: 市,

//    “district”: 县/区,

//    “province”:省

//},

//”srcAddress”:{：原寄地信息

//    “address”: 详细地址,

//    “city”: 市,

//    “district”: 县/区,

//    “province”: 省

//},

//cargoDetails:物品集合

//”name”:物品名称

//”count”:数量

//”weight”:重量

//”length”:长度

//”width”:宽度

//”height”:高度

3.3、订单确认/取消接口

接口代码：

public ApiResultModel callOrder(String cguid){ try{ //查询物流主信息（这个数据是我之前下单存的数据） TransMain transMain = transMainService.getById(cguid); //封装请求 MsgData msgData = new MsgData(); msgData.setOrderId(transMain.getOrderId());//客户订单号 msgData.setDealType("2");//客户订单操作标识 msgData.setTotalVolume(String.valueOf(transMain.getVolume()));//总体积 msgData.setTotalWeight(String.valueOf(transMain.getWeight()));//总重量 ArrayList<DocumentData> documentDatas = new ArrayList<>(); DocumentData documentData = new DocumentData(); documentData.setWaybillType("1");//运单号类型 1：母单 2 :子单 3 : 签回单 documentData.setWaybillNo(transMain.getTransNumber());//运单号 documentDatas.add(documentData); msgData.setWaybillNoInfoList(documentDatas);//顺丰运单号 String jsonStr = JSONObject.toJSONString(msgData); //请求顺丰取消订单接口 String result = callExpressNewAPIServiceUtil .callSFApi(ExpressServiceCodeEnum.EXP_RECE_UPDATE_ORDER.getCode(), jsonStr); //处理响应数据，根据自己的系统业务逻辑保存下单相应的数据 }catch (Exception e){ e.printStackTrace(); return $.error(); } }

请求参数：

//cguid：物流主键

3.4、路由查询接口

接口代码：

public ApiResultModel getById(@RequestBody MsgData msgData){ try{ msgData.setLanguage("zh-CN");//响应报文的语言 msgData.setTrackingType(1);//查询号类别 msgData.setMethodType(1);//路由查询类别 String msgDataJson = JSONObject.toJSONString(msgData); //请求路由查询接口 String result = callExpressNewAPIServiceUtil.callSFApi(ExpressServiceCodeEnum.EXP_RECE_SEARCH_ROUTES.getCode(), msgDataJson); //处理响应数据，根据自己的系统业务逻辑保存下单相应的数据 }catch (Exception e){ e.printStackTrace(); return $.error(); } }

请求参数：

{

        “trackingNumber”:[

    “8”

        ]

}

//{

//”trackingNumber”: 顺丰运单号集合

//}

3.5、云打印面单2.0接口

接口代码：

public void putFaceSheet(@RequestBody MsgData msgData, HttpServletResponse response){ try{ //处理请求参数 msgData.setVersion("2.0");//版本 msgData.setFileType("pdf");//生成面单文件格式 msgData.setSync("true");//是否同步 Date date = new Date(); SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:ss:mm"); List<DocumentData> documents = new ArrayList<>(); DocumentData documentData = new DocumentData(); //根据运单号查询物流信息 TransMain transMain = transMainService.getByTransNumber(msgData.getMasterWaybillNo()); //根据物流表主键查询收寄件信息 List<TransContactinfo> transContactinfos = transContactinfoService.selectByMainCguid(transMain.getCguid()); //根据物流表主键查询托寄物信息 List<TransCargodetail> transCargodetails = transCargodetailService.selectByMainCguid(transMain.getCguid()); //主物品 TransCargodetail transCargodetail = transCargodetails.get(0); //运单号 documentData.setMasterWaybillNo(msgData.getMasterWaybillNo()); //true:热敏纸上无印刷需要打印 documentData.setIsPrintLogo("true"); //打印时间 documentData.setPrintDateTime(sdf.format(date)); for (TransContactinfo transContactinfo : transContactinfos) { if(transContactinfo.getContactType() == 1){//寄件人 //寄件人 documentData.setFromName(transContactinfo.getContact()); //寄件人电话 documentData.setFromPhone(transContactinfo.getMobile()); //寄件人公司名称 documentData.setFromOrgName(transContactinfo.getCompany()); //寄件人地址 documentData.setFromAddress(transContactinfo.getAddress()); //寄件人邮编 documentData.setFromPostcode(transContactinfo.getPostCode()); continue; }//收件人 //目的地（路由信息） documentData.setDestRouteLabel(transContactinfo.getAddress()); //收件人姓名 documentData.setToName(transContactinfo.getContact()); //收件人电话 documentData.setToPhone(transContactinfo.getMobile()); //收件人公司名称 documentData.setToOrgName(transContactinfo.getCompany()); //收件人地址 documentData.setToAddress(transContactinfo.getAddress()); //收件人邮编 documentData.setToPostcode(transContactinfo.getPostCode()); } //付款方式（支持选项：寄付月结、寄付转第三方、寄付现结、到付） documentData.setPayment(transMain.getPaymoneyWay()==1?"寄付": transMain.getPaymoneyWay()==2?"到付": transMain.getPaymoneyWay()==3?"月结":"保密"); //二维码信息 //documentData.setTwoDimensionCode(); //托寄物 String entrustedArticles = IndexUtil.formatResName(transCargodetails); documentData.setEntrustedArticles(entrustedArticles); //件数 documentData.setPackageNumber(String.valueOf(transMain.getCount())); //计费重量 documentData.setChargedWeight(String.valueOf(transMain.getWeight())); //实际重量 documentData.setActualWeight(String.valueOf(transMain.getWeight())); //长*宽*高 String size = transCargodetail.getLength()+"*"+transCargodetail.getWidth()+"*"+transCargodetail.getHeight(); documentData.setSize(size); documents.add(documentData); msgData.setDocuments(documents);//业务数据         //解析为json格式的字符串 String jsonStr = JSONObject.toJSONString(msgData); //请求云打印面单接口 String result = callExpressNewAPIServiceUtil .callSFApi(ExpressServiceCodeEnum.COM_RECE_CLOUD_PRINT_WAYBILLS.getCode(), jsonStr); //处理响应数据，根据自己的系统业务逻辑保存下单相应的数据 }catch (Exception e){ e.printStackTrace(); System.out.println("pdf下载失败"); } }

请求参数：

{

        “templateCode”:”fm_150_standard_YryeOXwEo”,

        “masterWaybillNo”:”SF84″

}

//templateCode：打印模板编码

//masterWaybillNo:运单号

API响应需要根据自己的业务需求，顺丰还有其他的API接口这里我就展示这些吧，如果你的系统需要其他的API接口，请参考官网文档。官网地址我已经放到文章的顶部，感谢大家支持！