接口文档
1、 关于接口
接口为标准的 HTTP POST 协议,目前只开放了保税订单的创建、状态查询,直邮订单的创建、状态查询,保税商品的库存查询。
测试环境地址:http://119.29.6.201:8068/
测试环境的帐号:02010324,密钥:112233
测试环境联调通过之后,需要向深圳汇通天下物流有限公司索要正式的地址、帐号和密钥。
调用接口的时候需要传入以下参数:
id : 帐号,测试时使用 02010324
method : 需要调用的功能,具体请参考各项接口说明
returnStyle : 要求返回的数据格式, 可以传入 xml 或者 json ,需要注意的是,传入的复杂内容须为 xml ,暂时不支持 json 的传入参数。
datetime : 当前时间,传入的格式为: yyyyMMddHHmmss 例:19970102121314,为了数据安全,请保证传入的时间跟服务器时间保持在 1 个小时之内,为了保证安全性,超过范围,服务会拒绝服务。
content : 数据内容,需BASE64编码
verify : 数据效验码,用于验证数据安全和完整性,生成规则为 md5(id + datetime + base64的content +密钥)
Xml:
返回的数据:
<Result>
<Msg>运单预报成功</Msg>
<State>1</State>
<Data>
数据主体,可能是对象,也可能是单纯的数据
</Data>
<OpCode>0</OpCode>
</Result>
Json:
{
"Msg":"运单预报成功",
"State":1,"Data":数据主体,可能是对象,也可能是单纯的数据,
"OpCode":0
}
返回的数据中,如果成功的话State应该是返回 1 ,Msg则只是提示信息,调用失败的话State为 -1, Msg返回的是错误信息, OpCode 是操作类型,作为保留字段。
Data(内容主体) 则是根据不同的功能返回对应的对象
2、 接口说明
1) 订单预报接口
传入参数:
method : order.predict | 订单预报
content:
订单信息 ShipmentRequest | ||||
参数名 | 必录 | 数据类型 | 注释/说明 | |
ReferenceId | Y | varchar(25) | 客户单号 | |
Server | Y | varchar(16) | 走货渠道 | |
Amount | Y | int | 申报数量 | |
UnitPrice | Y | Decimal(16,2) | 申报单价 必须大于零 | |
TotalPrice | Y | Decimal(16,2) | 申报总价 | |
Currency | Y | varchar(16) | 币种 | |
Description | Y | varchar(100) | 申报品名 | |
DescriptionCn | Y | varchar(100) | 中文品名 | |
IsBattery | Y | Int | 是否电池 0:否,1:是,默认为 0 | |
BatteryLabel | Y/N | varchar(200) | 电池标号 当为电池件是,为必录项 | |
BatteryDescription | Y/N | Varchar(200) | 电池描述 当为电池件是,为必录项 | |
PackageType | Y | varchar(2) | 包裹类型 01:文件, 02:包裹 | |
AirwayBillNumber | N | varchar(25) | 运单号,推送时不需要,返回时提供 | |
Consignee 收件人 | PersonName | Y | varchar(25) | 收件人名 |
CompanyName | Y | varchar(50) | 收件人公司 | |
Address1 | Y | varchar(50) | 收件人地址一 | |
Address2 | Y | varchar(50) | 收件人地址二 | |
Address3 | Y | varchar(50) | 收件人地址三 | |
CityName | N | varchar(50) | 收件人城市 | |
PostalCode | N | varchar(10) | 收件人邮编 | |
CountryCode | Y | varchar(16) | 收件人国家二字代码 | |
PhoneNumber | Y | varchar(50) | 收件人电话 | |
FaxNumber | Y | varchar(50) | 收件人传真 | |
N | varchar(50) | 收件人邮箱 | ||
Consignor 发件人 | PersonName | Y | varchar(25) | 发件人名 |
CompanyName | Y | varchar(50) | 发件人公司 | |
Address1 | Y | varchar(50) | 发件人地址一 | |
Address2 | Y | varchar(50) | 发件人地址二 | |
Address3 | Y | varchar(50) | 发件人地址三 | |
CityName | N | varchar(50) | 发件人城市 | |
PostalCode | N | varchar(10) | 发件人邮编 | |
CountryCode | Y | varchar(16) | 发件人国家二字代码 | |
PhoneNumber | Y | varchar(50) | 发件人电话 | |
FaxNumber | Y | varchar(50) | 发件人传真 | |
N | varchar(50) | 发件人邮箱 | ||
Pieces | Number | Y | Int | 序号 |
Weight | Y | decimal(16, 2) | 重量 | |
Length | Y | decimal(16, 2) | 长度 | |
Width | Y | decimal(16, 2) | 宽度 | |
Height | Y | decimal(16, 2) | 高度 | |
LicensePlate | N | varchar(30) | JD号,推送时不需要,返回时提供 |
例文:
<ShipmentRequest>
<ReferenceId>RfId_20160518_232953</ReferenceId>
<Server>02001</Server>
<Amount>2</Amount>
<UnitPrice>100</UnitPrice>
<TotalPrice>200</TotalPrice>
<Currency>USD</Currency>
<Description>Description</Description>
<DescriptionCn>DescriptionCn</DescriptionCn>
<PackageType>01</PackageType>
<IsBattery>0</IsBattery>
<Consignee>
<PersonName>PersonName2</PersonName>
<CompanyName>CompanyName2</CompanyName>
<Address1>Address12</Address1>
<Address2>Address22</Address2>
<Address3>Address32</Address3>
<CityName>AARBURG ZUSTELLUNG</CityName>
<PostalCode>4663</PostalCode>
<CountryCode>CH</CountryCode>
<PhoneNumber>PhoneNumber2</PhoneNumber>
<FaxNumber>FaxNumber2</FaxNumber>
</Consignee>
<Consignor>
<PersonName>PersonName1</PersonName>
<CompanyName>CompanyName2</CompanyName>
<Address1>Address11</Address1>
<Address2>Address21</Address2>
<Address3>Address31</Address3>
<CityName>HONG KONG</CityName>
<PostalCode />
<CountryCode>HK</CountryCode>
<PhoneNumber>PhoneNumber1</PhoneNumber>
<FaxNumber>FaxNumber1</FaxNumber>
</Consignor>
<Pieces>
<Piece>
<Number>1</Number>
<Weight>1</Weight>
<Length>1</Length>
<Width>1</Width>
<Height>1</Height>
</Piece>
<Piece>
<Number>2</Number>
<Weight>2</Weight>
<Length>2</Length>
<Width>2</Width>
<Height>2</Height>
</Piece>
</Pieces>
</ShipmentRequest>
返回结果:
Xml:
<Result>
<Msg>运单预报成功</Msg>
<State>1</State>
<Data>
<ReferenceId>RfId_20160518_232953</ReferenceId>
<Server>02001</Server>
<Amount>2</Amount>
<UnitPrice>100</UnitPrice>
<TotalPrice>200</TotalPrice>
<Currency>USD</Currency>
<PackageType>01</PackageType>
<Description>Description</Description>
<DescriptionCn>DescriptionCn</DescriptionCn>
<IsBattery>0</IsBattery>
<BatteryLabel/>
<BatteryDescription/>
<AirwayBillNumber>3208718995</AirwayBillNumber>
<Consignee>
<PersonName>PersonName2</PersonName>
<CompanyName>CompanyName2</CompanyName>
<Address1>Address12</Address1>
<Address2>Address22</Address2>
<Address3>Address32</Address3>
<CityName>AARBURG ZUSTELLUNG</CityName>
<PostalCode>4663</PostalCode>
<CountryCode>CH</CountryCode>
<PhoneNumber>PhoneNumber2</PhoneNumber>
<FaxNumber>FaxNumber2</FaxNumber>
</Consignee>
<Consignor>
<PersonName>PersonName1</PersonName>
<CompanyName>CompanyName2</CompanyName>
<Address1>Address11</Address1>
<Address2>Address21</Address2>
<Address3>Address31</Address3>
<CityName>HONG KONG</CityName>
<PostalCode/>
<CountryCode>HK</CountryCode>
<PhoneNumber>PhoneNumber1</PhoneNumber>
<FaxNumber>FaxNumber1</FaxNumber>
</Consignor>
<Pieces>
<Piece>
<Number>1</Number>
<Weight>1</Weight>
<Length>1</Length>
<Width>1</Width>
<Height>1</Height>
<LicensePlate>JJD014600003214991040</LicensePlate>
</Piece>
<Piece>
<Number>2</Number>
<Weight>2</Weight>
<Length>2</Length>
<Width>2</Width>
<Height>2</Height>
<LicensePlate>JJD014600003214991041</LicensePlate>
</Piece>
</Pieces>
</Data>
<OpCode>0</OpCode>
</Result>
{
"Success":"true",
"NoticeMessage":"订单新增成功",
"response":{
"ENo":"667484933C","OrderNo":
"BC_DD011504-000009",
"WayBillNo":"800087979926",
"LogisticProviderID":"YTO"
}
}
:
{
"Msg":"运单预报成功",
"State":1,
"OpCode":0,
"Data":{
"ReferenceId":"RfId_20160518_233542",
"Server":"02001",
"Amount":2,
"UnitPrice":100.0,
"TotalPrice":200.0,
"Currency":"USD",
"Description":"Description",
"PackageType":"01",
"DescriptionCn":"DescriptionCn",
"IsBattery":0,
"BatteryLabel":"",
"BatteryDescription":"",
"AirwayBillNumber":"3208727944",
"Consignee":{
"PersonName":"PersonName2",
"CompanyName":"CompanyName2",
"Address1":"Address12",
"Address2":"Address22",
"Address3":"Address32","
CityName":"AARBURG ZUSTELLUNG",
"PostalCode":"4663",
"CountryCode":"CH",
"CountryName":null,
"PhoneNumber":"PhoneNumber2",
"FaxNumber":"FaxNumber2",
"EMail":null
},
"Consignor":{
"PersonName":"PersonName1",
"CompanyName":"CompanyName2",
"Address1":"Address11",
"Address2":"Address21",
"Address3":"Address31",
"CityName":"HONG KONG",
"PostalCode":"",
"CountryCode":"HK",
"CountryName":null,
"PhoneNumber":"PhoneNumber1",
"FaxNumber":"FaxNumber1",
"EMail":null
},
"Pieces":[
{
"Number":1,
"Weight":1.0,
"Length":1.0,
"Width":1.0,
"Height":1.0,
"LicensePlate":"JJD014600003214992051"
},
{
"Number":2,
"Weight":2.0,
"Length":2.0,
"Width":2.0,
"Height":2.0,
"LicensePlate":"JJD014600003214992052"
}
]
}
}
构建HTTP POST 请求
import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.List;
import net.kingtrans.order.common.Order;
import net.kingtrans.order.common.OrderItem;
import net.kingtrans.util.Convert;
import net.kingtrans.util.InvalidException;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.params.CoreConnectionPNames;
import org.apache.http.util.EntityUtils;
import org.apache.log4j.Logger;
import sun.misc.BASE64Encoder;
public class WGInterface {
private static Logger logger = Logger.getLogger(WGInterface.class);
//main方法接口测试
public static void main(String[] args) throws InvalidException, NoSuchAlgorithmException, UnsupportedEncodingException {
String content =
"<ShipmentRequest><ReferenceId>RfId_20160518_232953</ReferenceId><Server>02001</Server><Amount>2</Amount><UnitPrice>100</UnitPrice><TotalPrice>200</TotalPrice><Currency>USD</Currency>"+
"<Description>Description</Description><DescriptionCn>DescriptionCn</DescriptionCn><PackageType>01</PackageType><IsBattery>0</IsBattery>"+
"<Consignee><PersonName>PersonName2</PersonName><CompanyName>CompanyName2</CompanyName><Address1>Address12</Address1>"+
"<Address2>Address22</Address2><Address3>Address32</Address3><CityName>AARBURG ZUSTELLUNG</CityName><PostalCode>4663</PostalCode><CountryCode>CH</CountryCode>"+
"<PhoneNumber>PhoneNumber2</PhoneNumber><FaxNumber>FaxNumber2</FaxNumber></Consignee><Consignor><PersonName>PersonName1</PersonName>"+
"<CompanyName>CompanyName2</CompanyName><Address1>Address11</Address1><Address2>Address21</Address2><Address3>Address31</Address3>"+
"<CityName>HONG KONG</CityName><PostalCode /><CountryCode>HK</CountryCode><PhoneNumber>PhoneNumber1</PhoneNumber><FaxNumber>FaxNumber1</FaxNumber></Consignor>"+
"<Pieces><Piece><Number>1</Number><Weight>1</Weight><Length>1</Length><Width>1</Width><Height>1</Height>"+
"</Piece><Piece><Number>2</Number><Weight>2</Weight><Length>2</Length><Width>2</Width><Height>2</Height></Piece>"+
"</Pieces></ShipmentRequest>";
String contentBASE64 = getBase64(content);
String date = Convert.getNowDateTimeStr();
String key = "112233";
String id = "02010324";
//MD5加密
String verify = toMd5(id+date+contentBASE64+key);
HttpClient http = null;
HttpPost post = null;
String result = "";
try {
http = new DefaultHttpClient();
post = new HttpPost("http://119.29.6.201:8068/");
http.getParams().setParameter(
CoreConnectionPNames.CONNECTION_TIMEOUT, 120000);
http.getParams().setParameter(CoreConnectionPNames.SO_TIMEOUT,
120000);
List<NameValuePair> nvp = new ArrayList<NameValuePair>();
nvp.add(new BasicNameValuePair("id", "02010324"));
nvp.add(new BasicNameValuePair("method", "order.predict"));
nvp.add(new BasicNameValuePair("returnStyle", "json"));
nvp.add(new BasicNameValuePair("datetime", date));
nvp.add(new BasicNameValuePair("content", contentBASE64 ));
nvp.add(new BasicNameValuePair("verify", verify));
post.setEntity(new UrlEncodedFormEntity(nvp, "utf-8"));
HttpResponse response = http.execute(post);
HttpEntity entity = response.getEntity();
result = EntityUtils.toString(entity, "utf-8");
logger.info("返回的结果:" + result);
} catch (Exception e) {
e.printStackTrace();
throw new InvalidException("访问出错信息: " + e.getMessage());
} finally {
post.releaseConnection();
}
}