本土运单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 |
用户信息 |
示例
请求参数：
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 |
快递对象列表 |
示例
请求参数：
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.本土运单查费率
请求参数：
|
POST参数名 |
是否必填 |
说明 |
|
是 |
快递公司发放的key |
|
|
是 |
Shipment Json 对象序列化后字符串 |
Shipment对象
|
参数名 |
是否必填 |
类型 |
说明 |
|
是 |
String |
运营商,上对接网站创建本土运单，快递名称下拉框查看 |
|
|
是 |
|||
|
ShipTo |
是 |
ShipAddr |
收件人信息 |
|
Parcels |
是 |
List<Parcels> |
包裹列表 |
|
否 |
UPS GFP FREIGHT_CLASS 必填。其他不用填这个参数 |
||
|
否 |
Bool |
||
|
否 |
int |
ShipAddr对象
|
参数名 |
是否必填 |
类型 |
说明 |
|
是 |
String |
||
|
是 |
String |
||
|
否 |
String |
||
|
是 |
String |
||
|
Address2 |
是 |
String |
地址行2 |
|
收件人：是 寄件人：否 |
String |
||
|
是 |
String |
||
|
是 |
String |
国家(USA) ,目前只支持美国USA |
|
|
否 |
String |
||
|
否 |
Int |
1表示商业BUSINESS,2表示住宅RESIDENTIAL |
Parcel对象
|
参数名 |
是否必填 |
类型 |
说明 |
|
是 |
Decimal 2位小数 |
||
|
是 |
Decimal 2位小数 |
||
|
是 |
Decimal 2位小数 |
宽度 |
|
|
是 |
Decimal 2位小数 |
高度 |
|
|
否 |
Decimal 2位小数 |
保险额度，Carrier返回支持保险才可用 |
返回对象 Response
|
属性名 |
说明 |
|
Code |
状态码 200 - 成功返回 600 – 服务器异常 603 – 参数错误
|
|
Message |
描述返回错误信息 |
|
Rate |
Rate Json对象 – 费率信息 |
示例
请求参数：
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
实时接口:/Api/Express/CreateLabel2.ashx ,部分渠道可用,具体可用渠道请咨询技术支持
请求参数：
|
POST参数名 |
是否必填 |
说明 |
|
Key |
是 |
快递公司发放的key |
|
Data |
是 |
Shipment Json 对象序列化后的字符串 |
Shipment对象
|
参数名 |
是否必填 |
类型 |
说明 |
|
否 |
String |
||
|
Carrier |
是 |
String |
运营商 |
|
是 |
String |
运营商服务,上对接网站创建本土运单，快递服务下拉框查看 |
|
|
ShipFrom |
是 |
ShipAddr |
发件人信息 |
|
ShipTo |
是 |
ShipAddr |
收件人信息 |
|
Parcels |
是 |
List<Parcels> |
包裹列表 |
|
FreightCalss |
否 |
String |
UPS GFP FREIGHT_CLASS 必填。其他不用填这个参数 |
|
Signature |
否 |
Bool |
是否需要签名，默认不签名 |
|
否 |
Int |
面单尺寸 0表示4x6 1表示A4，默认4x6 |
|
|
Remark1 |
否 |
String |
备注1 |
|
Remark2 |
否 |
String |
备注2 |
|
否 |
int |
||
|
否 |
String |
||
|
否 |
Bool |
部分FedEx渠道使用(具体渠道请咨询技术支持),可能因FedEx地址类型问题,是否自动变换FedEx Ground/FedEx Home Delivery服务下单 |
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对象 – 订单的信息 |
示例
请求参数：
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数组 – 面单的信息 |
示例
请求参数：
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 |
描述返回错误信息 |
示例
请求参数：
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对象 – 地址信息 |
示例
请求参数：
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
}
}