仓配退货下单接口-速运类API
EXP_RECE_CREATE_REVERSE_ORDER
1. 功能描述
退货下单接口根据客户需要,可提供以下四个功能:
● 客户系统向顺丰下发退货订单
● 为订单分配运单号
● 筛单
● 路由注册(可选)
2. 接口定义
2.1. 公共参数
2.2. 公共请求参数
序号 |
参数列表 |
类型 |
是否必传 |
含义 |
1 |
已作废 |
String(64) |
是 |
|
2 |
requestID |
String(40) |
是 |
请求唯一号UUID |
3 |
serviceCode |
String(50) |
是 |
接口服务代码(EXP_RECE_CREATE_REVERSE_ORDER) |
4 |
timestamp |
long |
是 |
调用接口时间戳 |
5 |
已作废 |
String(128) |
条件 |
|
6 |
已作废 |
String |
条件 |
|
7 |
msgData |
String |
是 |
业务数据报文 |
2.3. 请求参数\ /OrderReverse
# |
属性名 |
类型(约束 |
必填 |
默认值 |
描述 |
1 |
language |
String(10) |
否 |
|
响应报文的语言,缺省值为zh-CN,目前支持以下值zh-CN表示中文简体,zh-TW或zh-HK或zh-MO表示中文繁体,en表示英文 |
2 |
orderId |
String(64) |
是 |
|
客户订单号 |
3 |
cargoDetails |
List |
是 |
|
拖寄物信息 |
4 |
origOrderId |
String(20) |
否 |
|
原订单号 |
5 |
oldClientCode |
List |
否 |
|
原顾客编码 |
6 |
serviceList |
List |
否 |
|
增值服务信息 |
7 |
contactInfoList |
List |
|
|
收寄双方信息 |
8 |
monthlyCard |
String(20) |
条件 |
|
顺丰月结卡号 |
9 |
payMethod |
Number (2) |
否 |
|
付款方式,支持以下值: 1:寄方付 2:收方付 3:第三方付 |
10 |
expressTypeId |
Number (5) |
否 |
|
快件产品类别,支持附录《快件产品类别表》的产品编码值,仅可使用与顺丰销售约定的快件产品。 |
11 |
sendStartTm |
Date |
否 |
|
要求上门取件开始时间,格式:YYYY-MM-DD HH24:MM:SS,示例:2012-7-30 09:30:00。 |
12 |
isCheck |
String(5) |
否 |
|
是否验货,1-验货,其他-不验货 |
13 |
shopName |
String(100) |
否 |
|
商家店铺名称 |
14 |
origWaybillNo |
String(15) |
条件 |
|
原运单号 |
15 |
orderType |
String(50) |
否 |
|
订单类型:退货订单,维修订单 |
16 |
bizTemplateCode |
String(100) |
否 |
|
业务配置代码,业务配置代码指BSP针对客户业务需求配置的一套接口处理逻辑,一个接入编码可对应多个业务配置代码。 |
17 |
refundAmount |
Nmuber(17,5) |
否 |
|
退款金额 |
18 |
remark |
String(100) |
否 |
|
备注 |
2.4.元素OrderReverse/List[ContactInfo]
# |
属性名 |
类型(约束) |
必填 |
默认值 |
描述 |
1 |
contactType |
Number (1) |
是 |
|
地址类型:1,寄件方信息2,到件方信息 |
2 |
company |
String(100) |
条件 |
|
公司名称 |
3 |
contact |
String(100) |
条件 |
|
联系人 |
4 |
tel |
String(20) |
条件 |
|
联系电话 |
5 |
mobile |
String(20) |
否 |
|
方手机 |
6 |
zoneCode |
String(30) |
条件 |
|
城市代码或国家代码,如果是跨境件,则此字段为必填。 |
7 |
country |
String(30) |
是 |
|
国家或地区 2位代码参照附录国家代码附件 |
8 |
province |
String(30) |
否 |
|
所在省级行政区名称,必须是标准的省级行政区名称如:北京、广东省、广西壮族自治区等;此字段影响原寄地代码识别,建议尽可能传该字段的值。 |
9 |
city |
String(100) |
否 |
|
所在地级行政区名称,必须是标准的城市称谓 如:北京 |
市、深圳市、大理白族自治州等;此字段影响原寄地代码识别,建议尽可能传该字段的值。 |
10 |
county |
String(30) |
否 |
|
所在县/区级行政区名称,必须是标准的县/区称谓, |
如:福田区,南涧彝族自治县、准格尔旗等。 |
11 |
address |
String(200) |
条件 |
|
详细地址,若province/city字段的值不传,此字段必须包含省市信息,避免影响原寄地代码识别,如:广东省深圳市福田区新洲十一街万基商务大厦10楼;若需要生成电子运单,则为必填。 |
12 |
postCode |
String(25) |
条件 |
|
邮编,跨境件必填(中国内地,港澳台互寄除外)。 |
13 |
email |
String(200) |
否 |
|
邮箱地址 |
2.5. 元素OrderReverse/List[CargoDetail]
# |
属性名 |
类型(约束) |
必填 |
默认值 |
描述 |
1 |
name |
String(128) |
是 |
|
货物名称,如果需要生成电子运单,则为必填。 |
2 |
count |
Number(5) |
条件 |
|
货物数量 跨境件报关需要填写 |
3 |
unit |
String(30) |
条件 |
|
货物单位,如:个、台、本,跨境件报关需要填写。 |
4 |
weight |
Number(16,3) |
条件 |
|
订单货物单位重量,包含子母件,单位千克,精确到小数点后3位跨境件报关需要填写。 |
5 |
amount |
Number(17,3) |
条件 |
|
货物单价,精确到小数点后3位,跨境件报关需要填写。 |
6 |
visualInspection |
String(100) |
否 |
|
外观 |
7 |
cargoSku |
String() |
否 |
|
商品编码 |
8 |
intelligentInspection |
Number (1) |
否 |
|
智能验货标识(1-是,0-否)(逆向物流) |
9 |
snCode |
String(4000) |
否 |
|
货物标识码(逆向物流) |
10 |
checkRemark |
String(4000) |
否 |
|
收货备注,如果商品需要收派员验货则要填写这一项。 |
2.6. 元素OrderReverse/List[Service]
# |
属性名 |
类型(约束) |
必填 |
默认值 |
描述 |
1 |
name |
String(20) |
是 |
|
增值服务名,如COD等。 |
2 |
value |
String(30) |
条件 |
|
增值服务扩展属性,参考增值服务传值说明。 |
3 |
value1 |
String(30) |
条件 |
|
增值服务扩展属性 |
2.7. 元素OrderReverse/List[Service]
# |
属性名 |
类型(约束) |
必填 |
默认值 |
描述 |
1 |
name |
String(20) |
是 |
|
增值服务名,如COD等。 |
2 |
value |
String(30) |
条件 |
|
增值服务扩展属性,参考增值服务传值说明。 |
3 |
value1 |
String(30) |
条件 |
|
增值服务扩展属性 |
2.8. 请求示例\应用场景(JSON)示例
请求报文:
{
"language":"zh_CN",
"orderId":"F2_20200604180946",
"cargoDetails":[
{
"amount":100.5111,
"count":2.365,
"currency":"HKD",
"cargoSku":"AAAA004",
"name":"护肤品1",
"unit":"个",
"weight":6.1
}],
"serviceList":[
{
"name":"INSURE",
"value":"3000"
}],
"contactInfoList": [
{
"address":"软件产业基地11栋",
"city":"深圳市",
"contact":"小曾",
"contactType":1,
"country":"CN",
"county":"南山区",
"mobile":"13480155048",
"postCode":"580058",
"province":"广东省",
"tel":"4006789888"
},
{
"address":"广东省广州市白云区湖北大厦",
"city":"",
"company":"顺丰速运",
"contact":"小邱",
"contactType":2,
"country":"CN",
"county":"",
"mobile":"13925211148",
"postCode":"580058",
"province":"",
"tel":"18688806057"
}],
"monthlyCard":"",
"payMethod":1,
"expressTypeId":1,
"volume":8.0,
"sendStartTm":"2020-03-10 10:00:00",
"refundAmount":8.0,
"isCheck":"1"
}
2.9. 返回示例\应用场景(JSON)示例
响应报文:
{
"apiResponseID": "000173271968963FA47C03E68000103F",
"apiErrorMsg": "",
"apiResultCode": "A1000",
"apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\": {\"orderId\":\"5ed9696e-a81d-4a5b-968d-182c2d8c09e0\",\"filterResult\":2,\"remark\":\"\",\"waybillNo\":\"SF7444400048449\"}"
}
{
"apiResponseID": "000173271968963FA47C03E68000103F",
"apiErrorMsg": "",
"apiResultCode": "A1000",
"apiResultData": "{\"success\":"\false\",\"errorCode\":\"8016\",\"errorMsg\":\"重复下单\",\"msgData\":null}"
}
3.1. 错误代码
3.1 (API)平台结果代码列表
3.2 业务异常代码
# |
errorCode |
描述 |
1 |
S0000 |
成功 |
2 |
S0001 |
非法的JSON格式 |
3 |
S0002 |
必填参数%s为空 |
4 |
S0003 |
系统发生数据错误或运行时异常 |
5 |
S0004 |
参数%s超过最大长度%d |
6 |
S0005 |
参数超过最大值 |
7 |
S0006 |
参数%s不能小于%d |
8 |
S0007 |
参数%s数据类型错误 |
速运类接口业务相关错误码