天地华宇开放平台接口说明
目录
开放平台开发接口介绍
开放平台是天地华宇为外部企业系统对接天地华宇系统提供服务的平台,而开放平台开发接口则是提供服务的基础,外部企业从天地华宇申请用户后,可以通过阅读本接口文档来帮助开发。
接口列表
开放平台访问地址
- 测试服务器地址: http://open.hoau.net:8180
- 正式服务器地址: http://open.hoau.net:8080
请求url示例:
http://open.hoau.net:8180/open-web/rs/waybill/query/F3060161
接口调用请求说明
1.接口发布方式:Restful
2.接口请求方式:GET,POST,PUT,DELETE
3.数据传输方式:json
4.Content-Type: application/json;charset=UTF-8
接口请求代码示例(Java Apache CXF):
WebClient client = WebClient.create("http://localhost:8080");
client.path("/open-web/rs/order/v1/add")
.accept("application/json;charset=UTF-8")
.type("application/json;charset=UTF-8");
String requestJson = "{\"companyCode\":\"hoau\",\"customerOrderNo\":\"NO123456\",\"senderName\":\"张三\",\"senderMobile\":\"13333333333\",\"senderProvince\":\"上海市\",\"senderCity\":\"上海市\",\"senderCounty\":\"闵行区\",\"senderAddress\":\"华翔路2239号\",\"receiverName\":\"李四\",\"receiverMobile\":\"13888888888\",\"receiverProvince\":\"广东省\",\"receiverCity\":\"深圳市\",\"receiverCounty\":\"福田区\",\"receiverAddress\":\"深南大道2012号\",\"cargoname\":\"衣服\",\"transportType\":\"DRD\",\"vistReceive\":\"YES\",\"deliveryType\":\"YES\"}";
client.header("companyId", "hoau");
client.header("reqTime", "2015-04-14 13:21:00");
client.header("token", "dGr69/UaDWChu9C4KLyMp8ObyKI=");
InputStream in = (InputStream) client.post(requestJson).getEntity();
String response = IOUtils.toString(in);
请求消息头参数说明
参数 | 是否必填 | 参数说明 |
---|---|---|
companyId | 是 | 用户id |
reqTime | 是 | 请求时间 |
token | 是 | 请求加密生成的签名 |
接口返回信息
接口调用返回json如下:
{
"result": null,
"errcode": "1000",
"errmsg": null
}
全局返回码说明
每次调用接口时,可能获得正确或错误的返回码,开发者可以根据返回码信息调试接口,排查错误,以下列出的是全局返回码,不包含具体业务相关错误码,具体业务相关错误码见具体接口信息
错误码 | 说明 |
---|---|
1000 | 成功 |
2001 | 访问权限错误,白名单验证错误 |
2002 | 数据安全错误,摘要验证错误或是时间戳验证超时 |
3001 | 参数错误 |
3002 | 业务规则判断错误 |
8000 | 业务异常 |
9000 | 未知错误 |
9999 | 系统异常 |
接口加密方案
开发者从天地华宇申请用户后,会为开发者分配用户id(用于网络中传输)与秘钥(用于加密),在每次接口调用前,开发者使用秘钥对该请求进行加密生成签名,并将用户id与生成的签名在http请求中传递给服务端(http请求的header中companyId存放用户id,token存放生成的签名),服务端对请求进行签名验证,验证通过则返回具体的业务结果,验证失败则返回相应的错误信息。
加密步骤
1.请求方式+"&"+uri+"&"+请求时间+"&"+请求参数
如果无请求参数则请求参数为空字符串
带参数:"POST"+"&"+"/open-web/rs/order/v1/add"+"&"+"2015-04-14 13:21:00"
+"&"+"{\"companyCode\":\"hoau\",\"customerOrderNo\":\"NO123456\",\"senderName\":\"张三\",\"senderMobile\":\"13333333333\",\"senderProvince\":\"上海市\",\"senderCity\":\"上海市\",\"senderCounty\":\"闵行区\",\"senderAddress\":\"华翔路2239号\",\"receiverName\":\"李四\",\"receiverMobile\":\"13888888888\",\"receiverProvince\":\"广东省\",\"receiverCity\":\"深圳市\",\"receiverCounty\":\"福田区\",\"receiverAddress\":\"深南大道2012号\",\"cargoname\":\"衣服\",\"transportType\":\"DRD\",\"vistReceive\":\"YES\",\"deliveryType\":\"YES\"}"
无参数:"GET"+"&"+"/open-web/rs/order/v1/query/NO123"+"&"+"2015-04-14 13:21:00"+"&"+""
2.对相加后的字符串进行HMAC-SHA1加密
3.对加密后的字符串进行Base64编码
加密代码示例(Java)
public class TokenUtil {
public static final String REQ_METHOD_GET = "GET";
public static final String REQ_METHOD_POST = "POST";
public static final String REQ_METHOD_PUT = "PUT";
public static final String REQ_METHOD_DELETE = "DELETE";
public static void main(String[] args) throws Exception {
TokenUtil.RequestEntity req = new TokenUtil.RequestEntity();
req.setReqMethod(REQ_METHOD_POST);
req.setUri("/open-web/rs/order/v1/add");
req.setReqTime("2015-04-14 13:21:00");
req.setContent("{\"companyCode\":\"hoau\",\"customerOrderNo\":\"NO123456\",\"senderName\":\"张三\",\"senderMobile\":\"13333333333\",\"senderProvince\":\"上海市\",\"senderCity\":\"上海市\",\"senderCounty\":\"闵行区\",\"senderAddress\":\"华翔路2239号\",\"receiverName\":\"李四\",\"receiverMobile\":\"13888888888\",\"receiverProvince\":\"广东省\",\"receiverCity\":\"深圳市\",\"receiverCounty\":\"福田区\",\"receiverAddress\":\"深南大道2012号\",\"cargoname\":\"衣服\",\"transportType\":\"DRD\",\"vistReceive\":\"YES\",\"deliveryType\":\"YES\"}");
req.setEncryptKey("asd123");
System.out.println(generateToken(req));
}
public static String generateToken(TokenUtil.RequestEntity req) throws Exception{
StringBuffer signatureStr = new StringBuffer();
signatureStr.append(req.getReqMethod())
.append("&");
signatureStr.append(req.getUri()).append("&");
signatureStr.append(req.getReqTime())
.append("&");
signatureStr.append(StringUtil.isEmpty(req.getContent()) ? "" : req.getContent());
String signature = Base64Coder.encode(HMACSHA1Util.HmacSHA1Encrypt(
signatureStr.toString(), req.getEncryptKey()));
return signature;
}
public static class RequestEntity{
/**
* 请求方式
*/
private String reqMethod;
/**
* 请求uri
*/
private String uri;
/**
* 请求时间
*/
private String reqTime;
/**
* 请求参数
*/
private String content;
/**
* 秘钥
*/
private String encryptKey;
public String getReqMethod() {
return reqMethod;
}
public void setReqMethod(String reqMethod) {
this.reqMethod = reqMethod;
}
public String getUri() {
return uri;
}
public void setUri(String uri) {
this.uri = uri;
}
public String getReqTime() {
return reqTime;
}
public void setReqTime(String reqTime) {
this.reqTime = reqTime;
}
public String getContent() {
return content;
}
public void setContent(String content) {
this.content = content;
}
public String getEncryptKey() {
return encryptKey;
}
public void setEncryptKey(String encryptKey) {
this.encryptKey = encryptKey;
}
}
}
加密工具类下载
接口调试
调试接口可以使用调用Restful接口工具调试,例如:谷歌浏览器Postman - REST Client (Packaged App)插件