华南通用下单对接文档


12-仓配退货下单接口

仓配退货下单接口-速运类API

EXP_RECE_CREATE_REVERSE_ORDER
1. 功能描述

退货下单接口根据客户需要,可提供以下四个功能:

● 客户系统向顺丰下发退货订单

● 为订单分配运单号

● 筛单

● 路由注册（可选）

2. 接口定义
2.1. 公共参数
名称 值
接口服务代码 EXP_RECE_CREATE_REVERSE_ORDER
生产环境地址 https://sz-mix.sf-express.com/backend/std/service/{hnCustomerCode} 生产{hnCustomerCode}请向大客获取。
沙箱环境地址 https://sz-mix.sit.sf-express.com/backend/std/service/{hnCustomerCode} 测试{hnCustomerCode}统一为11aeea6bdd7fbae1
批量交易 不支持
接口类型 接入
报文类型 JSON/XML
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）平台结果代码列表
标识 说明 【处理建议】
A1000 统一接入平台校验成功，调用后端服务成功； 注意：不代表后端业务处理成功，实际业务处理结果， 需要查看响应属性apiResultData中的详细结果
A1001 必传参数不可为空 serviceCode 已作废 requestID timestamp 已作废 msgData 不可为空
A1002 请求时效已过期 时效参考auth2 https://open.sf-express.com/customerService/395002?interId=590549&faqId=4
A1003 IP无效 参考常见问题 https://open.sf-express.com/customerService/395002?activeIndex=905584&interId=590549&faqId=2
A1004 无对应服务权限 联系销售经理，配置权限
A1005 流量受控 测试环境流量限制为5000，请不要在测试环境做压测
A1006 数字签名无效 参考常见问题 签名加解密问题 https://open.sf-express.com/customerService/395002?activeIndex=905584&interId=795986
A1007 重复请求 过一分钟在尝试
A1008 数据解密失败
A1009 目标服务异常或不可达
A1099 系统异常
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数据类型错误

速运类接口业务相关错误码

页面列表

ITEM_HTML