【第三方API】順豐電子面單SDK調用總結-java

一、獲得順豐電子面單SDK

    https://qiao.sf-express.com/index.html 豐橋系統中，文檔中心->SDK使用說明->運單自助打印SDK

    順豐電子面單SDK-1.0.3

    支持的開發環境： Java sdk 支持1.8及以上

二、啓動SDK本地服務：

    1.windows環境：

       ①將csim_waybill_print_service_V1.0.3.jar和RUN-SF-PRINTER.bat置於同一目錄下，雙擊RUN-SF-PRINTER.bat文件即可開啓本地運單打印服務。（這種情況也有可能開啓不成功，建議使用下面命令的方式）

        ②java -jar path [port]

例：（不填寫端口，則默認爲4040）

    

    2.linux環境：

        ①linux下安裝jdk1.8，執行命令：yum -y install java

        ②創建文件夾sf-service將csim_waybill_print_service_V1.0.3.jar放在文件夾中

        ③執行命令：chmod 777 csim_waybill_print_service_V1.0.3.jar 進行授權

        ④linux下進入sf-service文件，執行命令：nohup java -jar csim_waybill_print_service_V1.0.3.jar &

（注：nohup <程序名> &：命令在Unix/Linux中，普通進程用“&”符號放到後臺運行，則控制檯logout後，進程仍然繼續運行，起到守護進程的作用，使用nohup命令後，原程序的的標準輸出被自動改向到當前目錄下的nohup.out文件，起到了log的作用）。

    3.驗證服務器運行情況：

    瀏覽器：http://localhost:4040/servertest.html（4040爲啓動端口），顯示“OK!”則表示啓動成功

    4.Linux系統下需安裝黑體字體！！！

        ①查看安裝了哪些中文字體，命令：fc-list :lang=zh（如果命令不存在，則yum安裝fontconfig，命令：yum -y install fontconfig）

        ②cd /usr/share/fonts（沒有目錄則創建，命令：mkdir /usr/share/fonts）

        ③將順豐sdk裏帶的黑體字體放到該文件夾下

        ④chmod 755 *.ttf（linux命令chmod 755的含義）

        ⑤建立字體緩存

                mkfontscal （如果命令不存在，則yum安裝mkfontscale，命令：yum install mkfontscale）

                mkfontdir   （如果命令不存在，則yum安裝mkfontscale，命令：yum install mkfontdir）

                fc-cache -fv

        ⑥讓字體生效

                source /etc/profile 

                fc-match  （查看設置是否生效）

三、項目中引用順豐jar包

    方法一：將sf-csim-printer-api-1.0.3.jar包放在項目lib目錄下，並add as library（使用maven的不建議這樣做）

    方法二：將sf-csim-printer-api-1.0.3.jar包放到maven私服上，並在項目中引用依賴

<dependency>
    <groupId>sf-csim</groupId>
    <artifactId>printer-api</artifactId>
    <version>1.0.3</version>
</dependency>

四、調用demo

    1.使用210面單，使用SDK中生成圖片url和調用打印機url

/**
 * 調用打印機 彈出窗口 可選擇份數 適用於單張打印【三聯單】
 */
private static String printUrl = 
              "http://localhost:4040/sf/waybill/print?type=V3.0_poster_100mm210mm&output=print";
/**
 * 直接輸出圖片的BASE64編碼字符串 可以使用html標籤直接轉換成圖片【三聯單】
 */
private static String imageUrl = 
              "http://localhost:4040/sf/waybill/print?type=V3.0_poster_100mm210mm&output=image";

    2.打印電子面單方法  

   （注：打印url方法無需接返回的byte[]，自動會調起打印機）

@Override
public byte[] sfPrintWaybill(Map<String, Object> params, Integer printType) throws Exception {
    logger.info("進入順豐打印快遞面單接口:params={},printType={}", 
                                        JSONObject.toJSONString(params),printType);
    //1.根據業務需求確定請求地址
    String reqURL = "";
    if (printType == 1){
        reqURL = imageUrl;
    } else if (printType == 2){
        reqURL = printUrl;
    }
    //2.電子面單頂部是否需要logo  true：需要logo  false：不需要logo
    boolean topLogo = false;
    if(reqURL.contains("V2.0")&&topLogo){
        reqURL=reqURL.replace("V2.0", "V2.1");
    }
    if(reqURL.contains("V3.0")&&topLogo){
        reqURL=reqURL.replace("V3.0", "V3.1");
    }
    //3.構建WaybillDtoList
    List<WaybillDto> waybillDtoList = bulidWaybillDto(params);

    HttpURLConnection httpConn = buildHttpConn(reqURL);
    ObjectMapper objectMapper = new ObjectMapper();
    StringWriter stringWriter = new StringWriter();
    objectMapper.writeValue(stringWriter,waybillDtoList);

    httpConn.getOutputStream().write(stringWriter.toString().getBytes());
    httpConn.getOutputStream().flush();
    httpConn.getOutputStream().close();
    InputStream in = httpConn.getInputStream();

    BufferedReader in2=new BufferedReader(new InputStreamReader(in));
    String y="";
    String strImg="";
    while((y=in2.readLine())!=null){

        strImg=y.substring(y.indexOf("[")+1,y.length()-"]".length()-1);
        if(strImg.startsWith("\"")){
            strImg=strImg.substring(1,strImg.length());
        }
        if(strImg.endsWith("\"")){
            strImg=strImg.substring(0,strImg.length()-1);
        }

    }
    //將換行全部替換成空
    strImg=strImg.replace("\\n", "");
    byte[] bytes = (new Base64()).decode(strImg);

    return bytes;
}

    3.構建WaybillDtoList

private List<WaybillDto> bulidWaybillDto(Map<String, Object> params) throws Exception{
    List<WaybillDto> waybillDtoList = new ArrayList<>();
    WaybillDto dto = new WaybillDto();

    //對應clientCode
    dto.setAppId(clientCode);
    //對應checkWord
    dto.setAppKey(checkword);

    //快遞單號
    String mailNo = (String) params.get("mailNo");
    dto.setMailNo(mailNo);

    //收件人信息
    String receiverProvince = (String) params.get("receiverProvince");
    String receiverCity = (String) params.get("receiverCity");
    String receiverCounty = (String) params.get("receiverCounty");
    String receiverAddress = (String) params.get("receiverAddress");
    String receiverMobile = (String) params.get("receiverMobile");
    String receiverName = (String) params.get("receiverName");

    dto.setConsignerProvince(receiverProvince);
    dto.setConsignerCity(receiverCity);
    dto.setConsignerCounty(receiverCounty);
    dto.setConsignerAddress(receiverAddress); //詳細地址建議最多38個字，字段過長可能影響打印效果
    dto.setConsignerCompany(d_company);
    dto.setConsignerMobile(receiverMobile);
    dto.setConsignerName(receiverName);

    //寄件人信息
    dto.setDeliverProvince(j_province);
    dto.setDeliverCity(j_city);
    dto.setDeliverCounty(j_county);
    dto.setDeliverCompany(j_company);
    dto.setDeliverAddress(j_address);//詳細地址建議最多38個字，字段過長可能影響打印效果
    dto.setDeliverName(j_contact);
    dto.setDeliverMobile(j_tel);

    //原寄地代碼（下訂單接口順豐會返回，需要保存）
    String originCode = (String) params.get("originCode");
    dto.setZipCode(originCode);
    //目的地代碼（下訂單接口順豐會返回，需要保存）
    String destCode = (String) params.get("destCode");
    dto.setDestCode(destCode);

    //快遞類型
    //1 ：標準快遞   2.順豐特惠   3： 電商特惠   5：順豐次晨  6：順豐即日  7.電商速配   15：生鮮速配
    dto.setExpressType(1);
    //陸運E標示
    //業務類型爲“電商特惠、順豐特惠、電商專配、陸運件”則必須打印E標識，用以提示中轉場分揀爲陸運
    dto.setElectric("E");
    // 1-寄付 2-到付 3-第三方支付
    dto.setPayMethod(1);
    //加密項
    //加密寄件人及收件人名稱
    dto.setEncryptCustName(true);
    //加密寄件人及收件人聯繫手機
    dto.setEncryptMobile(true);

    //物品信息
    String orderNo = (String) params.get("orderNo");
    List<CargoInfoDto> cargoInfoList = new ArrayList<>();
    List<OrderDetailOutputDto> orderDetailList = 
                                    (List<OrderDetailOutputDto>) params.get("orderDetailList");
    for (OrderDetailOutputDto orderDetail : orderDetailList){
        CargoInfoDto cargo = new CargoInfoDto();
        cargo.setCargo(orderDetail.getCommodityName());
        cargo.setCargoCount(orderDetail.getNum());
        cargo.setCargoUnit("雙");
        cargo.setSku(orderDetail.getSkuNo());
        cargo.setRemark(orderNo);
        cargoInfoList.add(cargo);
    }
    dto.setCargoInfoDtoList(cargoInfoList);
    waybillDtoList.add(dto);
    logger.info("生成電子運單請求參數： "+ MyJsonUtil.object2json(dto));

    return waybillDtoList;

    4.構建Http連接

private HttpURLConnection buildHttpConn(String reqURL) throws Exception{
    /**注意 需要使用對應業務場景的url  **/
    URL myURL = new URL(reqURL);

    HttpURLConnection httpConn = (HttpURLConnection) myURL.openConnection();
    httpConn.setDoOutput(true);
    httpConn.setDoInput(true);
    httpConn.setUseCaches(false);
    httpConn.setRequestMethod("POST");
    httpConn.setRequestProperty("Content-Type", "application/json;charset=utf-8");
    httpConn.setConnectTimeout(10000);
    httpConn.setReadTimeout(2 * 5000);
    return httpConn;
}

五、controller層調用及前端

//預覽打印快遞單
byte[] imageByte = orderBackgroundApi.printWaybill(order,orderDeatilList,
        orderAddressList.get(0),orderConsignList.get(0),printType);


return JSONObject.toJSONString(imageByte);

controller層調用api，並返回byte數組給前端，前端頁面中使用<img>標籤，並使用src="data:image/png;base64,"方式來展示二進制圖片（需要對二進制數組進行base64編碼，順豐接口返回給我們的已經是經過base64編碼的字符串）

function printWaybill(orderId,orderNo) {
 layer.load(2);
    $.ajax({
        url:"/order/printWaybill.sc",
        type:"post",
        data:{orderId:orderId,orderNo:orderNo,printType:1},
        dataType:"json",
        success:function (data) {
            layer.closeAll();
            layer.open({
                type:1,
                title: '預覽',
                closeBtn:1,
                area:['850px','600px'],
                content:'<img src="data:image/png;base64,'+data+'" style="width:850px;"/>',
                btn: ['打印'],
                yes:function (index, layero) {
                    $.ajax({
                        url: "/order/printWaybill.sc",
                        type: "post",
                        data: {orderId: orderId, orderNo: orderNo, printType:2},
                        dataType: "json",
                        success:function (data) {
                            mmGrid.load();
                        }
                    });
                }
            });
        }
    })
}