对接第三方顺丰丰桥电子面单打印接口教程

发布于2022-08-07 21:22 阅读(1206) 评论(0) 点赞(9) 收藏(3)

对接第三方Api接口之顺丰丰桥电子面单

随着目前趋势的发展有非常多的科技公司研发的系统项目大部分都会有需要对接第三方接口的需求，但是也面临着这样的一个问题，有一些没有对接过第三方接口的小伙伴不清楚该如何接入，相信有很多自研项目，特别是电商类的项目都会有需要对接物流各种快递Api接口，那么接下来分享一个我自己对接过第三方系统Api接口栗子。

术语

对于一般人，电子面单的意思可能并不是很了解；说白了，就是快递员给你打印的快递单的电子版。
**功能描述：**接口提供给用户自主打单的服务，提供异步和同步返回面单pdf文件方式。
异步方式： 面单pdf文件会直接推送到用户配置的回调地址
同步方式： 不需要配置回调地址，接口会同步返回面单pdf文件的url地址，下载时需要请求头携带对应token

面单对接流程图

需要对接第三方系统Api首先要先了解它整个Api的调用过程，下面是一个对接第三方Api接口顺丰丰桥电子面单流程图。
在这里插入图片描述

Java实战栗子

**注意：**顺丰丰桥云面单打印接口调用默认的是异步调用，异步调用需要登录自己的顺丰丰桥账号到控制台，测试记录查询查看返回的报文，如果需要同步调用则需要在请求参数上设置Sync等于true，本栗子是同步调用，是否要同步调用或异步调用根据实际需求设置即可。

/**
	 * 云面单打印
	 */
	@SuppressWarnings("static-access")
	@Override
	public Result<FhhzdH> cloudPrint (FhhzdHDto entity,HttpServletResponse resp) throws UnsupportedEncodingException{		
		FhhzdH fhhzdH = mapper.selectByPrimaryKey(entity.getId);
		if (Common.isNull(fhhzdH)) {
			return new Result<FhhzdH>().setCode(BussErrorCode.ARGUMENT_NOT_VALID).setReason("单号为"+entity.getId+"数据不存在！");
		}
		if (Common.isEmpty(fhhzdH.getKddh())) {//快递单号
			return new Result<FhhzdH>().setCode(BussErrorCode.ARGUMENT_NOT_VALID).setReason("该单据还没有下单无法打印面单！");
		}
		//读取顺丰配置文件
		loadSfProperties();
		String msgData = getData(fhhzdH,TEMPLATECODE);//顺丰面单请求参数	
		CallExpressServiceTools client=CallExpressServiceTools.getInstance();	
		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("-", ""));
		params.put("serviceCode",COM_RECE_CLOUD_PRINT_WAYBILLS);// 接口服务码
		params.put("timestamp", timeStamp);		    
		params.put("msgData", msgData);		      
		params.put("msgDigest", client.getMsgDigest(msgData,timeStamp,CHECK_WORD));//数据签名		        
		String result = HttpClientUtil.post(CALL_URL_BOX, params);
		ShunFengResponse res = new Gson().fromJson(result, ShunFengResponse.class);     
	    String apiResultData = res.getApiResultData();	      
	    NoodleSheetData data = new Gson().fromJson(apiResultData, NoodleSheetData.class); 
		if (data.getSuccess() == false) {
			throw new RuntimeException(String.format("单据号为[%s]读取顺丰面单发生异常", fhhzdH.getDjh()));
		}
		/**
		 * 注意：如果是异步方式请求接口时不需要关注以下此部分内容，我这写的是同步，以下代码是要把顺丰云面单
		 * 以流的形式输出打印出来，默认是异步，同步需要设置sync为true 
		 * 封装顺丰相应参数请严格按照顺丰接口要求，书写实体类
		 * 
		 */
	    String token = data.getObj().getFiles().get(0).getToken();//顺丰面单返回的token
	    String url = data.getObj().getFiles().get(0).getUrl();//pdf文件的url下载地址
	    try {
          URL noodleUrl = new URL(url);
          URLConnection connection = noodleUrl.openConnection(); //创建连接     
          connection.setRequestProperty("X-Auth-token", token);//设置请求头（下载文件时需要的token,设置在请求头的 X-Auth-token 字段，有效期 24h）
          InputStream in = connection.getInputStream();
          byte[] image = Util.toByteArray(in);
          OutputStream out = resp.getOutputStream();
          out.write(image);
          out.flush();
          out.close();
      } catch (IOException e) {
          log.error("pdf文件转换发生异常！", e.getMessage());
          throw new RuntimeException(e.getMessage());
      }	   
		return null;
	}

请求示例\应用场景(JSON)示例

自定义模板编码，当需要使用模板编辑器编辑自定义区时，将自定义模板编码赋值该字段自定义模板必须是已发布的，且规格要和需要打印的模板对应

/**
	 * 云打印面单请求报文
	 * @param fhhzdH
	 * @param templateCode //模板编码
	 * @return
	 */
	private String getData (FhhzdH fhhzdH, String templateCode) {		
		SFNoodleParam param = new SFNoodleParam();
		param.setTemplateCode(templateCode);//模板编码
		param.setVersion("2.0");//版本号，传固定值:2.0
		param.setFileType("pdf");//文件类型
		param.setSync(true);//true 同步 false 异步(默认是异步，如果需要异步sync不需要作为参数传参)
		List<Documents> documents = new ArrayList<Documents>();
		Documents document = new Documents();
		document.setMasterWaybillNo(fhhzdH.getKddh());//顺丰下单时生成的快递单号	
		documents.add(document);
		param.setDocuments(documents);//业务数据		 
		String msgData = new Gson().toJson(param).toString();//转为json
		log.info("云打印面单实际请求----------------------------------"+msgData);
		return msgData;
	}