华南通用下单对接文档


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