华南通用下单对接文档


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