华南通用下单对接文档


11-换货下单接口

换货下单接口-速运类API

EXP_RECE_CREATE_EXCHANGE_ORDER

1. 功能描述
  1. 客户系统向顺丰下发订单
  2. 为订单分配运单号
  3. 筛单
2. 接口定义
2.1. 公共参数
名称
接口服务代码 EXP_RECE_CREATE_EXCHANGE_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) 接口服务代码(EX_RECE_CREATE_EXCHANGE_ORDER)
4 timestamp long 调用接口时间戳
5 已作废 String(128) 条件
6 已作废 String 条件
7 msgData String 业务数据报文
2.3. 请求参数\/Exchange
# 属性名 类型(约束) 必填 默认值 描述
1 language Number(1) 返回描述语语言 0:中文 1:英文 2:繁体
2 orderId String(64) 客户订单号
3 origOrderId String(64) 原订单号
4 origWaybillNo String(30) 原运单号
5 bizTemplateCode String(30) 业务配置代码,业务配置代码指BSP针对客户业务需求配置的一套接口处理逻辑,一个接入编码可对应多个业务配置代码。
6 exchangeType Number(1) 换货类型 2:收件后换,3:退换一体
7 isCheck String(5) 是否验货, 1-验货,其他-不验货
8 newOrder Order 新货订单(查看2.3)
9 oldOrder Order 旧货订(查看2.3)

2.3.1 元素Exchange/Order

# 属性名 类型(约束) 必填 默认值 描述
1 expressTypeId Number (5) 快件产品类别,支持附录《快件产品类别表》的产品编码值,仅可使用与顺丰销售约定的快件产品。
2 payMethod Number (2) 付款方式,支持以下值: 1:寄方付 2:收方付 3:第三方付
3 monthlyCard String(20) 条件 顺丰月结卡号
4 waybillNoInfoList List 运单号
5 remark String(100) 备注
6 sendStartTm Date BSP接收到报文的时间 只支持新单传入 要求上门取件开始时间,格式:YYYY-MM-DD HH24:MM:SS,示例:2012-7-30 09:30:00。
7 parcelQty Number(5) 1 包裹数,一个包裹对应一个运单号;若包裹数大于1,则返回一个母运单号和N-1个子运单号。
8 cargoDetails List 拖寄物信息
9 serviceList List 增值服务信息
10 contactInfoList List 收寄双方信息
11 totalLength Number(16, 5) 客户订单货物总长,单位厘米,精确到小数点后3位,包含子母件。
12 totalWidth Number(16, 5) 客户订单货物总宽,单位厘米,精确到小数点后3位,包含子母件。
13 totalHeight Number(16, 5) 客户订单货物总高,单位厘米,精确到小数点后5位,包含子母件。
14 totalvolume Number(16,5) 订单货物总体积,单位立方厘米,精确到小数点后3位,会用于计抛(是否计抛具体商务沟通中双方约定)。
15 totalWeight Number(17,5) 订单货物总重量,包含子母件,单位千克,精确到小数点后3位,如果提供此值,必须>0 。
16 totalNetWeight Nmuber(17,5) 商品总净重
17 custReferenceNo String(100) 客户参考编码:如客户原始订单号

2.3.2 元素Exchange/Order/List

# 属性名 类型(约束) 必填 默认值 描述
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) 邮箱地址
14 taxNo String(100) 税号

2.3.3 元素Exchange/Order/List

# 属性名 类型(约束) 必填 默认值 描述
1 name String(128) 货物名称,如果需要生成电子运单,则为必填。
2 goodsCode String(60) 商品编号
3 count Number(5) 条件 货物数量 跨境件报关需要填写
4 unit String(30) 条件 货物单位,如:个、台、本,跨境件报关需要填写。
5 weight Number(16,3) 条件 订单货物单位重量,包含子母件,单位千克,精确到小数点后3位跨境件报关需要填写。
6 amount Number(17,3) 条件 货物单价,精确到小数点后3位,跨境件报关需要填写。
7 visualInspection String(500) 条件 外观,如果商品需要收派员验货则要填写这一项。
8 checkRemark String(500) 收货备注,如果商品需要收派员验货则要填写这一项.
9 intelligentInspection Number (1) 智能验货标识(1-是,0-否)(逆向物流)
10 snCode String(4000) 货物标识码(逆向物流)

2.3.4 元素Exchange/Order/List

# 属性名 类型(约束) 必填\ 默认值 描述
1 name String(20) 增值服务名,如COD等。
2 value String(30) 条件 增值服务扩展属性,参考增值服务传值说明。
3 value1 String(30) 条件 增值服务扩展属性
2.4. 公共响应参数
# 属性名 类型(约束) 必填 默认值 描述
1 success String true 请求成功,false 请求失败
2 errorCode String 错误编码,S0000成功
3 errorMsg String 错误描述
4 msgData String 返回的详细数据
2.5. 响应参数\ /OrderExchangeResponse
# 属性名 类型(约束) 必填 默认值 描述
1 orderId String(64) 客户订单号
2 newWaybill List 新货运单号
3 oldWaybill List 旧货运单号
4 newOriginCode String(30) 新货的原寄地代码
5 newDestCode String(30) 新货的目的地代码
6 oldDestCode String(30) 旧货的目的地代码
7 filterResult Number(2) 筛单结果: 1:人工确认 2:可收派 3:不可以收派
8 remark String(100) 条件 如果filter_result=3时为必填,不可以收派的原因代码: 1:收方超范围 2:派方超范围 3-:其它原因 高峰管控提示信息 【数字】:【高峰管控提示信息】(如 4:温馨提示 ,1:春运延时)
9 routeLabelInfo List 条件 下单路由标签新数据结构参考下单接口 (和标准下单返回一致)
2.6. 请求示例\应用场景(JSON)示例

请求报文:

{
 "oldOrder": {
  "extraInfoList": [{
   "attrVal": "B0101020090015",
   "attrName": "channelCode"
  }],
  "expressTypeId": 1,
  "upstairs": false,
  "payMethod":1,
  "isReturnContactInfo": 0,
  "specialWarehouse": false,
  "cargoDetails": [{
   "intelligentInspection": 0,
   "name": "墨盒"
  }],
  "contactInfoList": [{
   "address": "上海市市辖区宝山区蕴川路1188弄166号",
   "province": "上海市",
   "city": "市辖区",
   "contact": "陈大雁",
   "county": "宝山区",
   "mobile": "13661855365",
   "company": "BTM",
   "contactType": 2
  }]
 },
 "orderId": "20190613161002003140269",
 "clientCode": "XXXXXX",
 "exchangeType": "3",
 "origWaybillNo": "SF7444438801705",
 "isCheck": "0",
 "language": "zh-CN",
 "newOrder": {
  "extraInfoList": [{
   "attrVal": "B0101020090015",
   "attrName": "channelCode"
  }],
  "expressTypeId": 2,
  "upstairs": false,
  "payMethod": 1,
  "isReturnContactInfo": 0,
  "specialWarehouse": false,
  "monthlyCard": "",
  "remark": "黑4.25",
  "cargoDetails": [{
   "intelligentInspection": 0,
   "name": "墨盒",
   "checkRemark": "黑4.25"
  }],
  "contactInfoList": [{
   "address": "上海市市辖区宝山区蕴川路1188弄166号",
   "province": "上海市",
   "city": "市辖区",
   "contact": "吴用",
   "county": "宝山区",
   "mobile": "17521084316",
   "company": "神罗科技",
   "contactType": 1
  }, {
   "address": "江苏省南京市浦口区浦街道新浦路105号江佑铂庭16幢101室",
   "province": "江苏省",
   "city": "南京市",
   "contact": "旗舰店",
   "county": "浦口区",
   "company": "链家",
   "contactType": 2,
   "tel": "13815887518"
  }]
 }
}
2.7. 返回示例\应用场景(JSON)示例

响应报文:

  • 成功响应:
{
    "return_code": "0000",
    "return_msg": "成功"
}
  • 失败报文-范例1
{
    "return_code": "1000",
    "return_msg": "系统异常"
}
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