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

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

一、了解官网 

        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":"10000054381916",

        "contact":"小曾",

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

        "contactType":1,

        "country":"CN",

        "postCode":"580058",

        "tel":"4006789888",

        "province":"广东省",

        "city":"深圳市",

        "county":"南山区"

    },

    {

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

        "company":"顺丰速运",

        "userCguid":"10000055717100",

        "contact":"小邱",

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

        "contactType":2,

        "country":"CN",

        "postCode":"580058",

        "tel":"18688806057",

        "province":"广东省",

        "city":"广州市",

        "county":"白云区"

    }

],

"cooperateSchemaId":"52f34431996240da839960b34ba9e380",

"paymoneyWay":1,

"transCorporationCguid":"25dsadsadas2321312dsadsa2322",

"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":[

    "444003077898"

        ]

}

//{

//"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":"SF7444463882584"

}

//templateCode:打印模板编码

//masterWaybillNo:运单号

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

  • 6
    点赞
  • 8
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 4
    评论
Java接入丰桥并实现下单查询功能可以通过以下步骤完成: 首先,需要引入丰桥SDK依赖,可以通过在项目的pom.xml文件中添加以下代码引入丰桥SDK: ```xml <dependency> <groupId>com.sf</groupId> <artifactId>sf-express-api-sdk</artifactId> <version>1.0.0</version> </dependency> ``` 然后,在代码中调用丰桥SDK提供的接口来实现下单和查询功能。下单功能可以通过调用`com.sf.api.client.SfExpressServiceClient`类的`createOrder`方法来创建订单,传入相应的参数,如发货人信息、收货人信息、包裹详情等。示例代码如下: ```java SfExpressServiceClient client = new SfExpressServiceClient(); CreateOrderRequest request = new CreateOrderRequest(); request.setShipperName("发货人姓名"); request.setShipperMobile("发货人手机号码"); // 更多发货人信息设置 request.setConsigneeName("收货人姓名"); request.setConsigneeMobile("收货人手机号码"); // 更多收货人信息设置 CreateOrderResponse response = client.createOrder(request); ``` 查询功能可以通过调用`com.sf.api.client.SfExpressServiceClient`类的`queryOrder`方法来查询订单状态,传入相应的参数,如订单号、客户订单号等。示例代码如下: ```java SfExpressServiceClient client = new SfExpressServiceClient(); QueryOrderRequest request = new QueryOrderRequest(); request.setOrderId("订单号"); // 更多查询参数设置 QueryOrderResponse response = client.queryOrder(request); ``` 以上就是使用Java接入丰桥并实现下单查询功能的简要步骤。需要注意的是,具体的参数设置和接口调用方式可能会有所不同,可以参考丰桥提供的官方文档进行具体实现。
评论 4
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

C吴新科

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值