本土运单API接口

一、基本信息

1.通信方式:

HTTP的POST方法

2.数据格式

响应数据采用JSON

3.请求参数

Head ContentType : application/x-www-form-urlencoded

Key(必填参数)

请求key(32位),公司提供给合作网站的识别字符串,用于识别和鉴定请求来源,避免未授权的非法访问

其它参数

按实际需要填写,见下面接口说明

4.响应数据

Code

结果状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

Message

描述返回错误信息

二、API说明

1.获取余额

/Api/UserInfo.ashx

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

Data

用户信息

 

示例

请求FromData参数:

Key = 88888888888888888888888888888888

返回值:

{

     "Code": "200",

     "Message": null,

     "Data": {

         "Balance": 888.88

     }

}

2.获取快递和快递服务

/Api/Express/GetCarrierList.ashx

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

Data

快递对象列表

 

示例

请求FromData参数:

Key = 88888888888888888888888888888888

返回值:

{

     "Code": "200",

     "Message": null,

     "Data": [{

         "ServiceList": ["FedEx SmartPost", "FedEx Home Delivery", "FedEx Ground"],

         "Name": "FedEx Test",

         "IsInsure": true,

         "IsMultParcel": true,

     }, {

         "ServiceList": ["usps_first_class_mail", "usps_media_mail", "usps_parcel_select", "usps_priority_mail", "usps_priority_mail_express", "usps_first_class_mail_international", "usps_priority_mail_international", "usps_priority_mail_express_international"],

         "Name": "USPS"

         "IsInsure": false,

         "IsMultParcel": true,

     }]

}

3.本土运单查费率

/Api/Express/Rates.ashx

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

Data

Shipment Json 对象序列化后字符串

 Shipment对象

参数名

是否必填

类型

说明

Carrier

String

运营商,上对接网站创建本土运单,快递名称下拉框查看

ShipFrom

ShipAddr

发件人信息

ShipTo

ShipAddr

收件人信息

Parcels

List<Parcels>

包裹列表

FreightCalss

String

UPS GFP FREIGHT_CLASS  必填。其他不用填这个参数

Signature

Bool

是否需要签名,默认不签名

WeightUnitType

int

重量单位类型,0表示lb,2表示oz,默认是0

 

ShipAddr对象

参数名

是否必填

类型

说明

PostalCode

String

邮编

Name

String

姓名

Company

String

公司

Address1

String

地址行1

Address2

String

地址行2

State

收件人:是

寄件人:否

String

City

String

城市

Country

String

国家(USA) ,目前只支持美国USA

PhoneNumber

String

电话号码

AddrType

Int

1表示商业BUSINESS,2表示住宅RESIDENTIAL

 

Parcel对象

参数名

是否必填

类型

说明

Weight

Decimal 2位小数

包裹重量

Length

Decimal 2位小数

长度

Width

Decimal 2位小数

宽度

Height

Decimal 2位小数

高度

Insure

Decimal 2位小数

保险额度,Carrier返回支持保险才可用

 

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

Rate

Rate Json对象 – 费率信息

 

示例

请求FromData参数:

Data = {

     "Carrier": "ups2",

     "ShipFrom": {

         "PostalCode": "47906",

         "Name": "xiaoyang hu",

         "Address1": "1138 anthrop dr",

         "Address2": null,

         "State": "IN",

         "City": "West Lafayette",

         "Country": "USA",

         "PhoneNumber": "6267104685",

         "AddrType": 1

     },

     "ShipTo": {

         "PostalCode": "60609",

         "Name": "Jing zhang",

         "Address1": "2023 w 35th st",

         "Address2": null,

         "State": "IL",

         "City": "Chicago",

         "Country": "USA",

         "PhoneNumber": "6267104685",

         "AddrType": 1

     },

     "Parcels": [{

         "Weight": 3,

         "Length": 22,

         "Width": 22,

         "Height": 22

     }]

}&Key = 88888888888888888888888888888888

返回值:

{

     "Code": "200",

     "Message": "",

     "Data": [{

         "RateId": "rate_fa3adcab1d084bd290fd92149a8aeb0c",

         "Carrier": "self_ups",

         "CarrierServiceLevel": "Ground",

         "CarrierServiceName": "Ground",

         "ChargeWeight": 3,

         "TotalCharge": 29.42,

         "PackageType": null

     }, {

         "RateId": "rate_fa9cdf649a33426b9cdfd3883f5ec8af",

         "Carrier": "self_ups",

         "CarrierServiceLevel": "3DaySelect",

         "CarrierServiceName": "3DaySelect",

         "ChargeWeight": 3,

         "TotalCharge": 77.59,

         "PackageType": null

     }, {

         "RateId": "rate_8a5d4079079348668e071a1ffdfed6dd",

         "Carrier": "self_ups",

         "CarrierServiceLevel": "NextDayAir",

         "CarrierServiceName": "NextDayAir",

         "ChargeWeight": 3,

         "TotalCharge": 182.84,

         "PackageType": null

     }]

}

4.本土运单下单

/Api/Express/CreateLabel.ashx

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

Data

Shipment Json 对象序列化后的字符串

 Shipment对象

参数名

是否必填

类型

说明

OrderNum

String

订单号,大于8位,需要有权限,空则自动生成。如无权限,则无需填写

Carrier

String

运营商

CarrierServiceLevel

String

运营商服务,上对接网站创建本土运单,快递服务下拉框查看

ShipFrom

ShipAddr

发件人信息

ShipTo

ShipAddr

收件人信息

Parcels

List<Parcels>

包裹列表

FreightCalss

String

UPS GFP FREIGHT_CLASS  必填。其他不用填这个参数

Signature

Bool

是否需要签名,默认不签名

LabelSize

Int

面单尺寸 0表示4x6 1表示A4,默认4x6

Remark1

String

备注1

Remark2

String

备注2

WeightUnitType

int

重量单位类型,0表示lb,2表示oz,默认是0

 

ShipAddr对象

参数名

是否必填

类型

说明

PostalCode

String

邮编

Name

String

姓名

Address1

String

地址行1

Address2

String

地址行2

State

String

City

String

城市

Country

String

国家(USA) ,目前只支持美国USA

PhoneNumber

String

电话号码

AddrType

收件人:是

寄件人:否

Int

1表示商业BUSINESS,2表示住宅RESIDENTIAL

 

Parcel对象

参数名

是否必填

类型

说明

Weight

Decimal 2位小数

包裹重量

Length

Decimal 2位小数

长度

Width

Decimal 2位小数

宽度

Height

Decimal 2位小数

高度

Insure

Decimal 2位小数

保险额度,Carrier返回支持保险才可用

Picking

String

拣货信息,Carrier返回支持才可用

 

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

Shipment

Shipment Json对象 – 订单的信息

 

示例

请求FromData参数:

Data = {

     "Carrier": "ups2",

     "CarrierServiceLevel": "Ground",

     "ShipFrom": {

         "PostalCode": "47906",

         "Name": "xiaoyang hu",

         "Address1": "1138 anthrop dr",

         "Address2": null,

         "State": "IN",

         "City": "West Lafayette",

         "Country": "USA",

         "PhoneNumber": "6267104685",

         "AddrType": 1

     },

     "ShipTo": {

         "PostalCode": "60609",

         "Name": "Jing zhang",

         "Address1": "2023 w 35th st",

         "Address2": null,

         "State": "IL",

         "City": "Chicago",

         "Country": "USA",

          "PhoneNumber": "6267104685",

         "AddrType": 1

     },

     "OrderNum": null,

     "Parcels": [{

         "Weight": 3,

         "Length": 22,

         "Width": 22,

         "Height": 22

     }]

}&Key = 88888888888888888888888888888888

返回值:

{

     "Code": "200",

     "Message": null,

     "Data": {

"LabelReady": true,   //面单是否已经准备好,如为false 、//ShipmentId,LabelUrl,TranckingNumbers没有数据,需要等待//10-100秒请求面单信息接口获取这几个数据

         "ShipmentId": "shp_f771f2934f7f48459a6c7998b40cfb0e",

         "LabelUrl": "http://localhost:55862/UploadFiles/Self/1Z13R10R0398374459.pdf",

         "ShippingWeight": 2,

         "FactWeight": 2,

         "ShippingPrice": 29.42,

         "TrackingNumbers": ["1Z13R10R0398374459"],

         "Carrier": "ups2",

         "CarrierServiceLevel": "Ground",

         "ShipFrom": {

              "PostalCode": "47906",

              "Name": "xiaoyang hu",

              "Address1": "1138 anthrop dr",

              "Address2": null,

              "State": "IN",

              "City": "West Lafayette",

              "Country": "USA",

              "PhoneNumber": "6267104685",

              "AddrType": 1

         },

         "ShipTo": {

              "PostalCode": "60609",

              "Name": "Jing zhang",

              "Address1": "2023 w 35th st",

              "Address2": null,

              "State": "IL",

              "City": "Chicago",

              "Country": "USA",

              "PhoneNumber": "6267104685",

              "AddrType": 1

         },

         "OrderNum": "KV10644787171",

         "Parcels": [{

              "TrackingNumber": null,

              "Weight": 3,

              "Length": 22,

              "Width": 22,

              "Height": 22

         }]

     }

}

5.获取面单信息

/Api/Express/LabelsInfo.ashx

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

Data

Json 字符串数组

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

LabelInfo

LabelInfo Json数组 – 面单的信息

 

示例

请求FromData参数:

Data = [

  "KV10645108889",

  "KV10645090385",

  "KV10645084825",

  "KV10645076260"

]&Key = 88888888888888888888888888888888

返回值:

{

     "Code": "200",

     "Message": null,

     "Data": [{

         "ShipmentId": "",

         "LabelReady": false,

         "LabelUrl": null,

         "TrackingNumbers": [],

         "OrderNum": "KV10645108889"

     }, {

         "ShipmentId": "9622001900008000264000794631631221",

         "LabelReady": true,

         "LabelUrl": "http://localhost/UploadFiles/EE/794631631221.pdf",

         "TrackingNumbers": ["794631631221"],

         "OrderNum": "KV10645090385"

     }, {

         "ShipmentId": "9622001900008000264000794631631221",

         "LabelReady": true,

         "LabelUrl": "http://localhost/UploadFiles/EE/794631631221.pdf",

         "TrackingNumbers": ["794631631221"],

         "OrderNum": "KV10645084825"

     }, {

         "ShipmentId": "9622001900008000264000794631631221",

         "LabelReady": true,

         "LabelUrl": "http://localhost/UploadFiles/EE/794631631221.pdf",

         "TrackingNumbers": ["794631631221"],

         "OrderNum": "KV10645076260"

     }]

}

 

 

6.面单退款

/Api/Express/LabelsCancel.ashx

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

OrderNum

订单号

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

 

示例

请求FromData参数:

OrderNum=KV10645076260&Key = 88888888888888888888888888888888

返回值:

{

     "Code": "200",

     "Message": null

}

 

7. 地址校验并返回地址类型

/Api/Express/AddressCheck.ashx

注意:不同快递对同一个地址的地址类型判断可能会不同,故该接口返回的地址类型不一定是正常的,但是98%以上是准确的,如果快递创建运单提示地址类型不对,最好可以手工选择地址类型

请求参数:

POST参数名

是否必填

说明

Key

快递公司发放的key

Data

ShipAddr Json对象 – 地址信息

 ShipAddr对象

参数名

是否必填

类型

说明

PostalCode

String

邮编

Name

String

姓名

Address1

String

地址行1

Address2

String

地址行2

State

String

City

String

城市

Country

String

国家(USA) ,目前只支持美国USA

PhoneNumber

String

电话号码

AddrType

Int

1表示商业BUSINESS,2表示住宅RESIDENTIAL

此接口不需要填写AddrType,正确的地址,返回结果会自动带这项

 

 

返回对象 Response

属性名

说明

Code

状态码

200 - 成功返回

600 – 服务器异常

603 – 参数错误

 

Message

描述返回错误信息

Data

ShipAddr Json对象 – 地址信息

 

示例

请求FromData参数:

Data = {

     "PostalCode": "91710",

     "Name": "Kevin Chen",

     "Address1": "14592111 Central Av",

     "Address2": null,

     "State": "CA",

     "City": "Chino",

     "Country": null,

     "CountryCode": null,

     "PhoneNumber": "6267104685",

     "AddrType":0

} &Key = 88888888888888888888888888888888

正确返回值:

{

     "Code": "200",

     "Message": null,

     "Data": {

         "PostalCode": "91710",

         "Name": "Kevin Chen",

         "Address1": "14592 Central Av",

         "Address2": null,

         "State": "CA",

         "City": "Chino",

         "Country": "USA",

         "CountryCode": "USA",

         "PhoneNumber": "6267104685",

         "AddrType": 1

     }

}

错误返回值:

{

     "Code": "603",

     "Message": "[address]Address not found",

     "Data": {

         "PostalCode": "91710",

         "Name": "Kevin Chen",

         "Address1": "14592111 Central Av",

         "Address2": null,

         "State": "CA",

         "City": "Chino",

         "Country": "USA",

         "CountryCode": "USA",

         "PhoneNumber": "6267104685",

         "AddrType": 0

     }

}