应用项目接口[API] --小包裹投递系统为了第三方系统整合[日

版本 1.11 更新时间:2018-10

Web Services URL :

• 测试服务器URL

http://bizexpress.yamatohk.com.hk/wsSPDS_UAT/JPServiceAPI.asmx

• 生产服务器URL

http://bizexpress.yamatohk.com.hk/wsSPDS/JPServiceAPI.asmx

• 只有认证的ip 地址允许访问这个URL
• 协议：被投递的请求和应答需要使用简单对象访问协议（SOAP）使用web服务定义语言（WDSL）和XML模式定义语言（XSD）
• 编码方式：UTF-8

web服务安全性

• 签名数据
  UserToken -- 用户标识（产品标识的组成成分）
  Preshared KEY -- 唯一的加密key （产品标识的组成成分）
  TimeStamp -- 时间戳
  Hash value -- 使用MD5计算出的一串不可逆的唯一的字符串
• 签名生成
  签名是通过使用md5 对 签名数据中的值进行计算生出成的
  例子：
  Signature Data
  UserToken = TESTUserName
  PresharedKey = E1m5R/a1K5ucl
  TimeStamp = 20180305100000
  MD5 Hash 2C9879663A311CB191F9B2454A9ACFE1

API 方法 --创建订单

• 描述：当你的系统中的目的地是日本，用户可以通过这个方法来创建新的订单，我们的系统会返回订单和一个被分配的shipment ID使用户来获取记录。用户在使用此功能之前需要有跟踪号。用户在使用此功能之前需要有跟踪号，用户可向我方询问跟踪号码范围。
• 当要使用这个方法时：无论何时需要去创建一个新的物流是都需要提前获取一个跟踪号码。

• 请求详细：
  参数：

  
  image.png

• 结果：
  订单结果：

  
  image.png
  image.png
  image.png
  image.png
  

  打包结果：

  
  image.png
  项目结果：
  image.png
  数据集结果：
  image.png

API 方法 --创建订单不需要TrackingNo

• 描述：用户可以通过这个方法来创建新的订单，我们的系统会返回订单和一个被分配的shipment ID使用户来获取记录。当用户没有tracking no时使用这个方法

• 当要使用这个方法时：无论何时需要去创建一个新的物流是都需要提前获取一个跟踪号码。 (文档这里有错误)

• 参数、结果：（与上图一致）

API方法--删除订单

• 描述：用户通过这个方法来删除我们系统中的订单，仅当订单没有被拾取可删除。
• 当要使用这个方法时：当用户需要去删除一个没有被拾取的物流时

• 请求详情
  参数：

  
  image.png

• 应答详情
  数据集：

  
  image.png

API方法--通过ReferenceNumber获取订单状态

• 描述：用户可以通过该方法获取订单，仅当被注册的订单能够获取。
• 当要使用这个方法时：当用户使用reference number获取他们的物流信息时

• 请求详情
  参数：

  
  image.png

• 应答详情
  表头:

  
  image.png
  

  获取结果：

  
  image.png

API方法 -- 通过TrackingNumber获取订单状态

• 描述：：用户可以通过该方法获取订单，仅当被注册的订单能够获取。
• 当要使用这个方法时：当用户使用TrackingNumber获取他们的物流信息时

• 请求详情：
  参数：

  
  image.png

• 应答详情
  表头：

  
  image.png
  

  获取结果：

  
  image.png

API方法 -- 通过ReferenceNumber获取标签

• 描述：用户通过该方法获取订单在我们的系统的标签

• 当要使用这个方法时：当用户使用ReferenceNumber获取标签时

• 请求详情：
  参数：

  
  image.png

• 应答详情：
  结果集：

  
  image.png

API方法 -- 通过TrackingNumber获取标签

• 描述：用户通过该方法获取订单在我们的系统的标签
• 当要使用这个方法时：当用户使用TrackingNumber获取标签时

• 请求详情：
  参数：

  
  image.png

• 应答详情：
  结果集：

  
  image.png

API方法 -- 更新物流时间

• 描述：用户可以通过该方法修改我们系统的物流时间，仅当订单没有去拾取时
• 当要使用这个方法时：当用户需要更新没有被拾取的物流时间时

• 请求详情：
  

  参数： image.png

• 应答详情：
  

  结果集： image.png

附录A

• 示例(c# .net)
• 生成签名

protected string GenerateHash(string userName, string token, DateTime timestamp) {
string timeStamp = timestamp.ToString("yyyyMMddHHmmss"); using (var md5 = MD5.Create())
{
var hash = md5.ComputeHash(System.Text.Encoding.ASCII.GetBytes(userName + token + timeStamp)); StringBuilder sb = new StringBuilder();
for (int i = 0; i < hash.Length; i++)
{
sb.Append(hash[i].ToString("X2")); }
return sb.ToString(); }
}

• 创建订单

wsUAT.JPServiceAPI k = new wsUAT.JPServiceAPI();
wsUAT.Order o = new wsUAT.Order(); o.ReferenceNumber = "TestAPIOrder";
o.ShipDate = new DateTime(2017, 12, 24); o.ConsigneeFirstName = "SiuLam"; o.ConsigneeLastName = "Wong"; o.ConsigneeJPFirstName = "SiuLam"; o.ConsigneeJPLastName = "Wong"; o.ConsigneeEmail = "wind.suen@yamatohk.com.hk"; o.ConsigneePhone = "22620641"; o.ConsigneePostalCode = "1048125"; o.ConsigneeCountry = "Japan"; o.ConsigneePrefecture = "TokyoTo"; o.ConsigneeCity = "Chuoku"; o.ConsigneeAddress1 = "Ginza"; o.ConsigneeAddress2 = "2-16-10"; o.BillToFirstName = "SiuLam";
o.BillToLastName = "Wong"; o.BillToJPFirstName = "SiuLam"; o.BillToJPLastName = "Wong";
o.BillToEmail = "wind.suen@yamatohk.com.hk"; o.BillToPhone = "22620641"; o.BillToPostalCode = "1048125"; o.BillToCountry = "Japan"; o.BillToPrefecture = "TokyoTo"; o.BillToCity = "Chuoku";
o.BillToAddress1 = "Ginza"; o.BillToAddress2 = "2-16-10"; o.HandlingType = "2";
o.PaymentTerms = "2";
o.AdvanceNotice = "0";
o.NoticeType = "0";
o.InvoiceCurrencyCode = "JPY"; o.OrderDescription = "TestOrderOnly"; o.DeliveryDate = new DateTime(2017, 12, 25); o.DeliveryTime = "20";

List<wsUAT.Package> lp = new List<wsUAT.Package>(); wsUAT.Package p = new wsUAT.Package();
p.PackageID = "p00001";
p.TrackingNo = "999900000013";
p.Weight = 10.5M;
p.Width = 32M;
p.Length = 20;
p.Height = 25.5M; p.ShipperNote1 = "testNote1"; p.ShipperNote2 = "testNote2"; wsUAT.Item i = new wsUAT.Item(); i.ItemCode = "code123"; i.ItemOrigin = "CN"; i.ItemWeight = 5.5M;
i.HSCode = "8008123"; i.UnitOfMeasurement = "BOX"; i.UnitValue = 350;
i.Quantity = 10;
i.DescriptionOfGoods = "TEST Objects";
List<wsUAT.Item> li = new List<wsUAT.Item>(); li.Add(i);
wsUAT.Item i2 = new wsUAT.Item(); i2.ItemCode = "code124";
i2.ItemOrigin = "CN";
i2.ItemWeight = 2.5M;
i2.HSCode = "8008123"; i2.UnitOfMeasurement = "BOX"; i2.UnitValue = 50;
i2.Quantity = 5;
i2.DescriptionOfGoods = "TEST Objects2"; li.Add(i2);
p.ListItem = li.ToArray(); lp.Add(p);
o.ListPackage = lp.ToArray();
DataTable dt = k.CreateOrder("Token” , “201801081214” , “KEY", signature, o);

附录B

• CreateOrder 返回 DataTable image.png

• CreateOrderWithoutTrackingNo 返回DataTable

  
  image.png

标签范例

image.png

说明：

image.png