【第三方API】顺丰API调用总结-java

86 阅读 0 评论 57 点赞

我是靠谱客的博主单身芹菜，这篇文章主要介绍【第三方API】顺丰API调用总结-java，现在分享给大家，希望可以做个参考。

一、获取顾客编码及校验码

https://qiao.sf-express.com/index.html 丰桥系统中申请api接口，获得url（调用地址）、clientCode（顾客编码）、checkword（校验码）。

url：http://bsp-oisp.sf-express.com/bsp-oisp/sfexpressService

二、XML报文说明

1.请求XML报文：

service 属性定义“服务名”；Head元素定义“顾客编码”

复制代码

1
2
3
<Request service="服务名" lang="zh-CN">
<Head>顾客编码</Head>
<Body>请求数据XML</Body>

2.响应XML报文：

Head元素值为“OK”或“ERR”；OK代表交易成功，ERR代表发生系统或业务异常，交易失败；对于批量交易场景，只能为成功/失败，无部分成功/部分失败

复制代码

1
2
3
4
<Response service="服务名">
<Head>OK|ERR</HEAD>
<Body>正常响应数据XML</Body>
<ERROR code="NNNN">错误详细信息</ERROR>

三、API接口详情

1.下订单接口（OrderService）：

①客户系统向顺丰下发订单 ②为订单分配运单号

复制代码

/**
* 获取顺丰下订单接口xml
* @param params
* @return
*/
private String getOrderServiceRequestXml(Map<String,String> params){
//订单号
String orderNo = params.get("orderNo");
//收件人
String receiverName = params.get("receiverName");
//收件人电话
String receiverMobile = params.get("receiverMobile");
//收件人详细地址
String receiverAddress = params.get("address");
//商品名称
String commodityName = params.get("commodityName");
//商品数量
String orderNum = params.get("orderNum");
StringBuilder strBuilder = new StringBuilder();
strBuilder.append("<Request service='OrderService' lang='zh-CN'>");
strBuilder.append("<Head>" + clientCode + "</Head>");
strBuilder.append("<Body>");
strBuilder.append("<Order").append(" ");
strBuilder.append("orderid='" + orderNo.toString().trim() + "" + "'").append(" ");
//返回顺丰运单号
strBuilder.append("is_gen_bill_no='1'").append(" ");
//寄件方信息
strBuilder.append("j_company='" + j_company + "'").append(" ");
strBuilder.append("j_contact='" + j_contact + "'").append(" ");
strBuilder.append("j_tel='" + j_tel + "'").append(" ");
strBuilder.append("j_address='" + j_province+j_city+j_county+j_address + "'").append(" ");
//收件方信息
strBuilder.append("d_company='" + d_company + "'").append(" ");
strBuilder.append("d_contact='" + receiverName.toString().trim() + "'").append(" ");
strBuilder.append("d_tel='" + receiverMobile.toString().trim() + "'").append(" ");
strBuilder.append("d_address='" + receiverAddress.toString().trim() + "'").append(" ");
strBuilder.append(" > ");
//货物信息
strBuilder.append("<Cargo").append(" ");
strBuilder.append("name='" + commodityName + "'").append(" ");
strBuilder.append("count='" + orderNum.toString() + "'").append(" ");
strBuilder.append("unit='双'").append(">");
strBuilder.append("</Cargo>");
strBuilder.append("</Order>");
strBuilder.append("</Body>");
strBuilder.append("</Request>");
return strBuilder.toString();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
/**
* 获取顺丰下订单接口xml
* @param params
* @return
*/
private String getOrderServiceRequestXml(Map<String,String> params){
//订单号
String orderNo = params.get("orderNo");
//收件人
String receiverName = params.get("receiverName");
//收件人电话
String receiverMobile = params.get("receiverMobile");
//收件人详细地址
String receiverAddress = params.get("address");
//商品名称
String commodityName = params.get("commodityName");
//商品数量
String orderNum = params.get("orderNum");
StringBuilder strBuilder = new StringBuilder();
strBuilder.append("<Request service='OrderService' lang='zh-CN'>");
strBuilder.append("<Head>" + clientCode + "</Head>");
strBuilder.append("<Body>");
strBuilder.append("<Order").append(" ");
strBuilder.append("orderid='" + orderNo.toString().trim() + "" + "'").append(" ");
//返回顺丰运单号
strBuilder.append("is_gen_bill_no='1'").append(" ");
//寄件方信息
strBuilder.append("j_company='" + j_company + "'").append(" ");
strBuilder.append("j_contact='" + j_contact + "'").append(" ");
strBuilder.append("j_tel='" + j_tel + "'").append(" ");
strBuilder.append("j_address='" + j_province+j_city+j_county+j_address + "'").append(" ");
//收件方信息
strBuilder.append("d_company='" + d_company + "'").append(" ");
strBuilder.append("d_contact='" + receiverName.toString().trim() + "'").append(" ");
strBuilder.append("d_tel='" + receiverMobile.toString().trim() + "'").append(" ");
strBuilder.append("d_address='" + receiverAddress.toString().trim() + "'").append(" ");
strBuilder.append(" > ");
//货物信息
strBuilder.append("<Cargo").append(" ");
strBuilder.append("name='" + commodityName + "'").append(" ");
strBuilder.append("count='" + orderNum.toString() + "'").append(" ");
strBuilder.append("unit='双'").append(">");
strBuilder.append("</Cargo>");
strBuilder.append("</Order>");
strBuilder.append("</Body>");
strBuilder.append("</Request>");
return strBuilder.toString();
}

2.订单结果查询接口（OrderSearchService）：

因Internet环境下，网络不是绝对可靠，用户系统下订单到顺丰后，不一定可以收到顺丰系统返回的数据，此接口用于在未收到返回数据时，查询下订单（含筛选）接口客户订单当前的处理情况。重复下单时可调用此接口查询下单顺丰单号

复制代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/**
* 获取顺丰订单结果查询接口xml
* @param params
* @return
*/
private String getOrderSearchServiceRequestXml(Map<String,String> params){
String orderNo = params.get("orderNo");
StringBuilder strBuilder = new StringBuilder();
strBuilder.append("<Request service='OrderSearchService' lang='zh-CN'>");
strBuilder.append("<Head>" + clientCode + "</Head>");
strBuilder.append("<Body>");
strBuilder.append("<OrderSearch").append(" ");
strBuilder.append("orderid='" + orderNo.toString().trim() + "" + "'").append(" > ");
strBuilder.append("</OrderSearch>");
strBuilder.append("</Body>");
strBuilder.append("</Request>");
return strBuilder.toString();
}

3.路由查询接口（RouteService）：

支持两类查询方式：①根据顺丰运单号查询 ②根据客户订单号查询

复制代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/**
* 获取顺丰路由查询接口xml
* @param params
* @return
*/
private String getRouteServiceRequestXml(Map<String,String> params){
String orderNo = params.get("orderNo");
StringBuilder strBuilder = new StringBuilder();
strBuilder.append("<Request service='RouteService' lang='zh-CN'>");
strBuilder.append("<Head>" + clientCode + "</Head>");
strBuilder.append("<Body>");
strBuilder.append("<RouteRequest").append(" ");
strBuilder.append("tracking_type='2'").append(" ");
strBuilder.append("tracking_number='" + orderNo.toString().trim() + "" + "'").append(" >");
strBuilder.append("</RouteRequest>");
strBuilder.append("</Body>");
strBuilder.append("</Request>");
return strBuilder.toString();
}

三、API接口调用

①把XML报文与checkword前后连接

②把连接后的字符串做MD5编码

③把MD5编码后的数据进行Base64编码，此时编码后的字符串即为校验码

复制代码

1
2
3
//接口url
@Value("${express.sf.url}")
private String url = "http://bsp-oisp.sf-express.com/bsp-oisp/sfexpressService"

复制代码

/**
* 顺丰接口
* @param params
* @param type
1-下订单接口
2-订单结果查询接口 3-路由查询接口
* @return
*/
@Override
public SfExpressResponse sfExpressMethod(Map<String,String> params, int type) throws Exception{
logger.info("进入顺丰接口:params={},type={}", JSONObject.toJSONString(params),type);
if (type < 1){
logger.warn("调用接口类型传错");
return null;
}
String requestXml = "";
String methodName = "";
if (type == 1){
//1.获取下单xml
requestXml = getOrderServiceRequestXml(params);
methodName = "orderSerivce";
} else if (type == 2){
//1.获取订单结果查询xml
requestXml = getOrderSearchServiceRequestXml(params);
methodName = "orderSearchService";
} else if (type == 3){
//1.获取订单物流路由
requestXml = getRouteServiceRequestXml(params);
methodName = "routeService";
}
//2.xml+checkword
String verifyCode = requestXml + checkword;
//3.MD5加密 + Base64编码
MessageDigest md5 = MessageDigest.getInstance("MD5");
md5.update(verifyCode.getBytes("utf8"));
verifyCode = Base64Util.encode(md5.digest());
//4.post 请求
Map<String, Object> toHttpParams = new HashMap<>();
toHttpParams.put("xml",requestXml);
toHttpParams.put("verifyCode",verifyCode);
logger.info("请求顺丰接口"+methodName, toHttpParams.toString());
String resultStr = HttpExtUtil.doPost(url, toHttpParams);
logger.info("请求顺丰接口"+methodName+",result="+resultStr);
SfExpressResponse response = (SfExpressResponse)
                                               XMLUtil.convertToObject(SfExpressResponse.class,resultStr);
return response;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
/**
* 顺丰接口
* @param params
* @param type
1-下订单接口
2-订单结果查询接口 3-路由查询接口
* @return
*/
@Override
public SfExpressResponse sfExpressMethod(Map<String,String> params, int type) throws Exception{
logger.info("进入顺丰接口:params={},type={}", JSONObject.toJSONString(params),type);
if (type < 1){
logger.warn("调用接口类型传错");
return null;
}
String requestXml = "";
String methodName = "";
if (type == 1){
//1.获取下单xml
requestXml = getOrderServiceRequestXml(params);
methodName = "orderSerivce";
} else if (type == 2){
//1.获取订单结果查询xml
requestXml = getOrderSearchServiceRequestXml(params);
methodName = "orderSearchService";
} else if (type == 3){
//1.获取订单物流路由
requestXml = getRouteServiceRequestXml(params);
methodName = "routeService";
}
//2.xml+checkword
String verifyCode = requestXml + checkword;
//3.MD5加密 + Base64编码
MessageDigest md5 = MessageDigest.getInstance("MD5");
md5.update(verifyCode.getBytes("utf8"));
verifyCode = Base64Util.encode(md5.digest());
//4.post 请求
Map<String, Object> toHttpParams = new HashMap<>();
toHttpParams.put("xml",requestXml);
toHttpParams.put("verifyCode",verifyCode);
logger.info("请求顺丰接口"+methodName, toHttpParams.toString());
String resultStr = HttpExtUtil.doPost(url, toHttpParams);
logger.info("请求顺丰接口"+methodName+",result="+resultStr);
SfExpressResponse response = (SfExpressResponse)
                                               XMLUtil.convertToObject(SfExpressResponse.class,resultStr);
return response;
}

四、响应XML解析

综合三个接口的response xml，将SfExpressResponse定义如下（树状结构对象）：

复制代码

/**
* 顺丰接口response对象
* author: jing.mn
* date: 2018/4/9 16:17
* copyright wonhigh.net.cn
*/
@XmlAccessorType(XmlAccessType.FIELD)
@XmlRootElement(name = "Response")
public class SfExpressResponse implements Serializable {
private static final long serialVersionUID = 1L;
//响应状态
@XmlElement(name = "Head")
private String Head;
//响应失败原因
@XmlElement(name = "ERROR")
private ERROR ERROR;
//响应结果
@XmlElement(name = "Body")
private Body Body;
@XmlAccessorType(XmlAccessType.NONE)
public static class ERROR {
@XmlAttribute(name = "code")
private String code;
@XmlValue
private String text;
public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
public String getText() {
return text;
}
public void setText(String text) {
this.text = text;
}
}
@XmlAccessorType(XmlAccessType.NONE)
public static class Body {
@XmlElement(name = "OrderResponse")
private OrderResponse OrderResponse;
@XmlElement(name = "RouteResponse")
private RouteResponse RouteResponse;
public SfExpressResponse.OrderResponse getOrderResponse() {
return OrderResponse;
}
public void setOrderResponse(SfExpressResponse.OrderResponse orderResponse) {
OrderResponse = orderResponse;
}
public SfExpressResponse.RouteResponse getRouteResponse() {
return RouteResponse;
}
public void setRouteResponse(SfExpressResponse.RouteResponse routeResponse) {
RouteResponse = routeResponse;
}
}
@XmlRootElement(name="OrderResponse")
@XmlAccessorType(XmlAccessType.NONE)
public static class OrderResponse {
//订单号
@XmlAttribute(name = "orderid")
private String orderId;
//运单号
@XmlAttribute(name = "mailno")
private String mailNo;
//原寄地区域代码(可用于顺丰电子运单标签打印)
@XmlAttribute(name = "origincode")
private String originCode;
//目的地区域代码(可用于顺丰电子运单标签打印)
@XmlAttribute(name = "destcode")
private String destCode;
//筛单结果：1：人工确认 2：可收派 3：不可以收派
@XmlAttribute(name = "filter_result")
private String filterResult;
public String getOrderId() {
return orderId;
}
public void setOrderId(String orderId) {
this.orderId = orderId;
}
public String getMailNo() {
return mailNo;
}
public void setMailNo(String mailNo) {
this.mailNo = mailNo;
}
public String getOriginCode() {
return originCode;
}
public void setOriginCode(String originCode) {
this.originCode = originCode;
}
public String getDestCode() {
return destCode;
}
public void setDestCode(String destCode) {
this.destCode = destCode;
}
public String getFilterResult() {
return filterResult;
}
public void setFilterResult(String filterResult) {
this.filterResult = filterResult;
}
}
@XmlRootElement(name="RouteResponse")
@XmlAccessorType(XmlAccessType.NONE)
public static class RouteResponse {
//运单号
@XmlAttribute(name = "mailno")
private String mailNo;
//路由
@XmlElement(name = "Route")
private List<Route> Route ;
public String getMailNo() {
return mailNo;
}
public void setMailNo(String mailNo) {
this.mailNo = mailNo;
}
public List<SfExpressResponse.Route> getRoute() {
return Route;
}
public void setRoute(List<SfExpressResponse.Route> route) {
Route = route;
}
}
@XmlRootElement(name="Route")
@XmlAccessorType(XmlAccessType.NONE)
public static class Route {
//路由节点发生的时间
@XmlAttribute(name = "accept_time")
private String acceptTime;
//路由节点具体描述
@XmlAttribute(name = "remark")
private String remark;
//路由节点操作码
@XmlAttribute(name = "opcode")
private String opcode;
public String getAcceptTime() {
return acceptTime;
}
public void setAcceptTime(String acceptTime) {
this.acceptTime = acceptTime;
}
public String getRemark() {
return remark;
}
public void setRemark(String remark) {
this.remark = remark;
}
public String getOpcode() {
return opcode;
}
public void setOpcode(String opcode) {
this.opcode = opcode;
}
}
public String getHead() {
return Head;
}
public void setHead(String head) {
Head = head;
}
public SfExpressResponse.ERROR getERROR() {
return ERROR;
}
public void setERROR(SfExpressResponse.ERROR ERROR) {
this.ERROR = ERROR;
}
public SfExpressResponse.Body getBody() {
return Body;
}
public void setBody(SfExpressResponse.Body body) {
Body = body;
}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
/**
* 顺丰接口response对象
* author: jing.mn
* date: 2018/4/9 16:17
* copyright wonhigh.net.cn
*/
@XmlAccessorType(XmlAccessType.FIELD)
@XmlRootElement(name = "Response")
public class SfExpressResponse implements Serializable {
private static final long serialVersionUID = 1L;
//响应状态
@XmlElement(name = "Head")
private String Head;
//响应失败原因
@XmlElement(name = "ERROR")
private ERROR ERROR;
//响应结果
@XmlElement(name = "Body")
private Body Body;
@XmlAccessorType(XmlAccessType.NONE)
public static class ERROR {
@XmlAttribute(name = "code")
private String code;
@XmlValue
private String text;
public String getCode() {
return code;
}
public void setCode(String code) {
this.code = code;
}
public String getText() {
return text;
}
public void setText(String text) {
this.text = text;
}
}
@XmlAccessorType(XmlAccessType.NONE)
public static class Body {
@XmlElement(name = "OrderResponse")
private OrderResponse OrderResponse;
@XmlElement(name = "RouteResponse")
private RouteResponse RouteResponse;
public SfExpressResponse.OrderResponse getOrderResponse() {
return OrderResponse;
}
public void setOrderResponse(SfExpressResponse.OrderResponse orderResponse) {
OrderResponse = orderResponse;
}
public SfExpressResponse.RouteResponse getRouteResponse() {
return RouteResponse;
}
public void setRouteResponse(SfExpressResponse.RouteResponse routeResponse) {
RouteResponse = routeResponse;
}
}
@XmlRootElement(name="OrderResponse")
@XmlAccessorType(XmlAccessType.NONE)
public static class OrderResponse {
//订单号
@XmlAttribute(name = "orderid")
private String orderId;
//运单号
@XmlAttribute(name = "mailno")
private String mailNo;
//原寄地区域代码(可用于顺丰电子运单标签打印)
@XmlAttribute(name = "origincode")
private String originCode;
//目的地区域代码(可用于顺丰电子运单标签打印)
@XmlAttribute(name = "destcode")
private String destCode;
//筛单结果：1：人工确认 2：可收派 3：不可以收派
@XmlAttribute(name = "filter_result")
private String filterResult;
public String getOrderId() {
return orderId;
}
public void setOrderId(String orderId) {
this.orderId = orderId;
}
public String getMailNo() {
return mailNo;
}
public void setMailNo(String mailNo) {
this.mailNo = mailNo;
}
public String getOriginCode() {
return originCode;
}
public void setOriginCode(String originCode) {
this.originCode = originCode;
}
public String getDestCode() {
return destCode;
}
public void setDestCode(String destCode) {
this.destCode = destCode;
}
public String getFilterResult() {
return filterResult;
}
public void setFilterResult(String filterResult) {
this.filterResult = filterResult;
}
}
@XmlRootElement(name="RouteResponse")
@XmlAccessorType(XmlAccessType.NONE)
public static class RouteResponse {
//运单号
@XmlAttribute(name = "mailno")
private String mailNo;
//路由
@XmlElement(name = "Route")
private List<Route> Route ;
public String getMailNo() {
return mailNo;
}
public void setMailNo(String mailNo) {
this.mailNo = mailNo;
}
public List<SfExpressResponse.Route> getRoute() {
return Route;
}
public void setRoute(List<SfExpressResponse.Route> route) {
Route = route;
}
}
@XmlRootElement(name="Route")
@XmlAccessorType(XmlAccessType.NONE)
public static class Route {
//路由节点发生的时间
@XmlAttribute(name = "accept_time")
private String acceptTime;
//路由节点具体描述
@XmlAttribute(name = "remark")
private String remark;
//路由节点操作码
@XmlAttribute(name = "opcode")
private String opcode;
public String getAcceptTime() {
return acceptTime;
}
public void setAcceptTime(String acceptTime) {
this.acceptTime = acceptTime;
}
public String getRemark() {
return remark;
}
public void setRemark(String remark) {
this.remark = remark;
}
public String getOpcode() {
return opcode;
}
public void setOpcode(String opcode) {
this.opcode = opcode;
}
}
public String getHead() {
return Head;
}
public void setHead(String head) {
Head = head;
}
public SfExpressResponse.ERROR getERROR() {
return ERROR;
}
public void setERROR(SfExpressResponse.ERROR ERROR) {
this.ERROR = ERROR;
}
public SfExpressResponse.Body getBody() {
return Body;
}
public void setBody(SfExpressResponse.Body body) {
Body = body;
}
}