华南通用下单对接文档


1-增值服务推荐接口

增值服务推荐接口-速运类API

EXP_RECE_PSDS_RECOMMEND_VAS

1. 功能描述
  • 主要是提供增值服务推荐的查询功能。
2. 接口定义
2.1. 公共参数
名称
接口服务代码 EXP_RECE_PSDS_RECOMMEND_VAS
生产环境地址 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
2.2. 公共请求参数
序号 参数列表 类型 是否必传 含义
1 已作废 String(64)
2 requestID String(40) 请求唯一号UUID
3 serviceCode String(50) 接口服务代码
4 timestamp long 调用接口时间戳
5 已作废 String(128) 条件
6 已作废 Number 条件
7 msgData String 业务数据报文
2.3. 请求参数\ /RecommendVasReq
# 参数字段 参数名称 是否必填 数据类型 备注
1 traceId 溯源ID String 用于数据埋点追踪,必须唯一,推荐使用UUID,CX会员ID
2 expressType bsp产品编号 String 如: 1表示S1 顺丰特惠2表示S2标快
3 prodPrice 产品价格 Double 数字,如:25.1
4 srcProvince 原寄地省 String 如:广东省
5 srcCity 原寄地市 String 如:深圳市
6 srcCounty 原寄地区 String 如:南山区
7 destProvince 到方地址省 String 如:广东省
8 destCity 到方地址市 String 如:深圳市
9 destCounty 到方地址区 String 如:南山区
10 sendTime 寄件时间/预约上门时间 String 格式为:yyyy-MM-dd HH:mm:ss
11 orderTime 下单时间 String 格式为:yyyy-MM-dd HH:mm:ss,为空默认系统当前时间
12 weight 重量 Double
13 weightUnit 重量单位 Integer 如类型:1(千克);2(克);3(吨);4(英镑);默认千克
14 length Double 数字
15 width Double 数字
16 height Double 数字
17 lengthUnit 长度单位 Integer 如类型:1(厘米);2(米);3(千米);4(英寸)。空默认为厘米
18 payMethod 付款方式 String 如:1.寄付;2.到付;3.寄转第三方;4.到转第三方
19 monthlyCard 月结卡号 String 如:7556000455
20 packageNumber 件数 Integer 数字
21 commodityNameList 托寄物名称 List 支持多个,如:[海鲜,水果]
22 srcAddress 原寄地详细地址 String 原寄地详细地址
23 destAddress 目的地详细地址 String 详细收件地址
24 destPostalCode 海外目的国家邮编 String 当目的为海外国家时,此字段必填
25 applyLink 适用环节 String 0:下单环节;1:收件环节;2:派件环节;默认为0;
26 overseasCountryCode 海外国家代码 String 如:US
27 singleTicketReq 单票信息 Object 重货增值服务需传,json报文样例:参照2.3
28 singleProductReq 单子件信息 List 重货增值服务需传,json报文样例:参照2.4
29 specialService 特殊增值服务 String 1:高峰加价服务(IN100),目前只有高峰加价,如果多个“,”分割。此增值服务费绑定
30 orderService 订单增值服务 String 如:IN01,IN02;如果多个用“,”分割最多支持10个;
31 clientCode 接入码 String 如:fcjj123456当为接入码场景时此字段不能为空;
32 orderType 订单类型 String 如31/32/33/34
33 labelFresh 保鲜标签 List label_fresh 1代表保鲜 0代表非保鲜。 直接透传大数据接口字段
34 payCountry 付款国家 String 透传至PVS计价用
35 arrivalTime 快件预计到达时间 String 格式为:yyyy-MM-dd HH:mm:ss;就是ptcs返回的预计送达时间
36 srcPhoneNum 手机号码 String 付款方式为寄付或寄转第三方付传入寄方电话,若为到付传收方电话;(号码需加密)

2.3.1 元素 singleTicketReq

# 属性名 类型(约束) 必填 默认值 描述
1 realTotalWeight Integer 单票实重,单位kg
2 piecesNumber Integer 单票件数

2.3.2 元素 singleTicketReq

# 属性名 类型(约束) 必填 默认值 描述
1 singleProductNo List 子件单号列表
2 singleLength Integer 子件长度,单位米
3 singleWidth Integer 子件宽度,单位米
4 singleHeight Integer 子件高度,单位米
5 singleWeight Integer 子件实重,单位kg
6 quantity Integer 子件同规格数

2.3.3 元素 cargoProperty

# 属性名 类型(约束) 必填 默认值 描述
1 cargoFresh List 冷冻属性 1:冷冻 0:不冷冻
2 cargoFreeze Integer 冷冻属性 1:冷冻 0:不冷冻
3 cargoValue Integer 高价属性 1:高价 0:不高价
4 cargoFragileTerminal Integer 易碎属性 1:易碎 0:非易碎
5 cargoInflammable Integer 易燃属性 A: 易燃固体 RE:易燃液体 可能为空字符串
2.4. 公共响应参数
# 属性名 类型(约束) 必填 默认值 描述
1 success String true 请求成功,false 请求失败
2 errorCode String 错误编码,S0000成功
3 errorMsg String 错误描述
4 msgData String 返回的详细数据
2.5. 响应参数\ /cargoProperty
# 参数字段 参数名称 数据类型 备注
1 recommendedType 服务推荐类型 Integer 如:1-绑定服务,2-可选服务,3-附加费(加项),4-附加费(减项),5-默认绑定可取消,6-可选服务不可取消;7-取消
2 vasCode 服务代码 String 如:IN67
3 vasName 服务名称 String 如:保鲜服务
4 floorPrice 增值服务价格 Double 如:22.1
5 currency 币种 String 如:CNY(人民币)
6 chargedWeight 计费重量 Double 如:22.3
7 arrivalTime 最快到达时间 String 格式为:yyyy-MM-dd HH:mm:ss
8 cutOffTime 截单时间 String 格式为:yyyy-MM-dd HH:mm:ss
9 mutexVas 互斥增值服务 String 如:IN02 保价
10 timelinessTips 时效提醒 String 如:温馨提示:已超出时效收寄范围,请查验质量谨慎操作
11 freightBinding 付款方式是否与运费绑定 Integer 如:0,否;1,是
12 requiredInformation 补充必填信息 String 如:声明价值,报关方式,展会方式等。json报文,具体参照2.3
13 feeCode 增值服费用代码 Integer 增值服费用代码,如1
14 minInsuredPrice 最低保价价格 Double 最低保价价格
15 maxInsuredPrice 最低声明价值 Double 最低声明价值
16 useCoupon 是否支持顺丰券支付 Integer 如:0,否;1,是
17 stressRecommend 是否重点推荐 Integer 0 正常 1:优先推荐 2 次级推荐
18 extendAttForKY 重货扩展字段 String 返回值json报文,具体参照2.7
19 conditionJsonInfo 必填信息扩展字段 String 1、当增值服务为空或者空字符串,该字段不会返回出去。2、返回值为对象数组,格式:[{},{}] 具体参照2.8
20 extJson 增值服务扩展自定义字段说明 String 参照 3.5
21 priorityCode 优先推荐编码 String 根据配置返回 如 B0 ,A0
22 recommendIndex 推荐指数 Integer 目前只有acsp使用
23 order 按照算法推荐顺序 Integer 目前只有acsp使用
24 vasOrder 按照psds系统配置返回增值服务顺序 Float 全渠道字段,前端根据需要进行使用

2.5.1 元素 extendAttForKY

增值服务 Json报文 字段说明\
大件入户IN98 { “value”:“0”, “value1”:“1”, “value2”:“1”, “value3”:"", “value4”:"" } value 是否存在单件重量大于等于60kg , “1”是,”0”否value1value2value3value4 大件入户金额重货更改了注释
宅配延伸IN116 {“value”:[{“serviceId”:“1213”,“serviceName”:“一体机套餐”,“subServices”:[{“subItemCode”:“AA”,“subItemName”:“家电组装”}]},{“serviceId”:“123212”,“serviceName”:“按摩椅套餐”,“subServices”:[{“subItemCode”:“BB”,“subItemName”:“衣柜组装”}]}],“value1”:"",“value2”:"",“value3”:"",“value4”:""} serviceId:套餐ID;serviceName::套餐名称;subServices:套餐子详情;subItemCode:服务规则编码;subItemName:服务项名称;

2.5.2 元素增值服务说明

增值 服务 Json报文 字段说明
保价IN02 { “name”:“声明价值”, “writeType”:“1”, “validate”:"(20000,999999999)", “extendVal”: “1”} name : 必填信息名称writeType: 为填写方式 1: 文本输入框 2:单选项框 3:多选项框 4:数字输入框extendVal 如果为1 ,则认为不可修改声明价值
正式报关IN07 {“name”:“报关方式”,“writeType”:“2”,“childList”:[{“sort”:1,“name”:“简易报关”,“value”:“1”},{“sort”:2,“name”:“正式报关”,“value”:“2”},{“sort”:3,“name”:“海运报关”,“value”:“3”}]} name : 必填信息名称sort : 排序字段writeType: 为填写方式 1: 文本输入框2:单选项框3:多选项框4:数字输入框childList : 二级必填信息选项
展会服务IN60 {“name”:“展会方式”,“writeType”:“2”,“childList”:[{“sort”:1,“name”:“参展”,“value”:“1”},{“sort”:2,“name”:“退展”,“value”:“2”},{“sort”:3,“name”:“参展+退展”,“value”:“3”}]} 同上
代收货款IN01 {“name”:“代收信息”,“writeType”:“0”,“childList”:[{“sort”:1,“name”:“代收卡号”,“writeType”:“4”},{“sort”:2,“name”:“代收金额”,“writeType”:“4”}]} 同上
定时派送(指定时段)IN26 {“name”:“派送时段”,“writeType”:“2”,“childList”:[{“sort”:1,“name”:"[09:00–11:00)",“value”:“1”},{“sort”:2,“name”:"[11:00-13:00)",“value”:“2”},{“sort”:3,“name”:"[13:00-15:00)",“value”:“3”},{“sort”:4,“name”:"[15:00-17:00)",“value”:“4”},{“sort”:5,“name”:"[17:00-19:00)",“value”:“5”},{“sort”:6,“name”:"[19:00-21:00)",“value”:“6”}]} 同上
签单返还(纸质回单)IN03 {“name”:“签单方式”,“writeType”:“3”,“childList”:[{“sort”:1,“name”:“签名”,“value”:“1”},{“sort”:2,“name”:“盖章”,“value”:“2”},{“sort”:3,“name”:“登记身份证”,“value”:“3”},{“sort”:4,“name”:“收取身份证复印件”,“value”:“4”}]} 同上
原单转寄退回IN101 {“name”:“退回类型”,“writeType”:“2”,“childList”:[{“sort”:1,“name”:“同城转寄”,“value”:“1”},{“sort”:2,“name”:“异地转寄”,“value”:“2”},{“sort”:3,“name”:“同城退回”,“value”:“3”},{“sort”:4,“name”:“异地退回”,“value”:“4”},{“sort”:5,“name”:“原单退回”,“value”:“5”}]} 同上
电子图片IN91 {“name”:“验收方式”,“writeType”:“3”,“childList”:[{“sort”:1,“name”:“身份证正面”,“value”:“1”},{“sort”:2,“name”:“身份证反面”,“value”:“2”},{“sort”:3,“name”:“手持身份证上半身照”,“value”:“3”},{“sort”:4,“name”:“代签人身份证正面”,“value”:“4”},{“sort”:5,“name”:“代签人身份证反面”,“value”:“5”},{“sort”:6,“name”:“代签人手持身份证上半身照”,“value”:“6”},{“sort”:7,“name”:“收件人身份证正面方协议空白处照”,“value”:“7”},{“sort”:8,“name”:“手持协议照”,“value”:“8”},{“sort”:9,“name”:“NFC身份证验证”,“value”:“9”},{“sort”:10,“name”:“OCR身份证识别”,“value”:“10”},{“sort”:11,“name”:“ETC(车身45°/签收单/设备激活照)”,“value”:“11”},{“sort”:12,“name”:“签收回执”,“value”:“12”},{“sort”:13,“name”:“签单返还电子图片”,“value”:“13”}]} 同上
木质包装IN31 {“name”:“木质包装类型”,“writeType”:“2”,“childList”:[{“sort”:1,“name”:“木架”,“value”:“A”,“writeType”:“0”,“childList”:[{“sort”:1,“name”:“长”,“writeType”:“4”},{“sort”:2,“name”:“宽”,“writeType”:“4”},{“sort”:3,“name”:“高”,“writeType”:“4”}]},{“sort”:2,“name”:“木箱”,“value”:“B”,“writeType”:“0”,“childList”:[{“sort”:1,“name”:“长”,“writeType”:“4”},{“sort”:2,“name”:“宽”,“writeType”:“4”},{“sort”:3,“name”:“高”,“writeType”:“4”}]},{“sort”:3,“name”:“标准托盘”,“value”:“C”,“writeType”:“0”,“childList”:[{“sort”:1,“name”:“重量”,“writeType”:“4”},{“sort”:2,“name”:“件数”,“writeType”:“4”}]},{“sort”:4,“name”:“非标准托盘”,“value”:“D”,“childList”:[{“sort”:1,“name”:“重量”,“writeType”:“4”},{“sort”:2,“name”:“件数”,“writeType”:“4”},{“sort”:3,“name”:“费用”,“writeType”:“4”}]}]} 同上
IN59签收确认 {“name”:“签收确认”,“writeType”:“2”,“childList”:[{“sort”:1,“name”:“口令码验证”,“value”:“1”},{“sort”:2,“name”:“身份证验证”,“value”:“2”},{“sort”:3,“name”:“口令码和身份证验证”,“value”:“3”}]} 同上
特安IN21 { “name”:“声明价值”, “writeType”:“1”, “validate”:"(20000,999999999)", “extendVal”: “1”} name : 必填信息名称writeType: 为填写方式 1: 文本输入框2:单选项框3:多选项框4:数字输入框extendVal 如果为1 ,则认为不可修改声明价值
到付折扣IN109 { “name”:“优惠卡号”, “writeType”:“1” } 同上
安装服务IN103 { “name”:“安装内容”, “writeType”:“2”, “childList”:[ { “sort”:1, “name”:“跑步机”, “value”:“1” } ] } 同上
定时派送IN26 {“writeType”:“2”,“name”:“定时派送时间段”,“childList”:[{“name”:“2020-10-27”,“sort”:1,“value”:[“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-10-28”,“sort”:2,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-10-29”,“sort”:3,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-10-30”,“sort”:4,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-10-31”,“sort”:5,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-11-01”,“sort”:6,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-11-02”,“sort”:7,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]},{“name”:“2020-11-03”,“sort”:8,“value”:[“09:00-11:00”,“11:00-13:00”,“13:00-15:00”,“15:00-17:00”,“17:00-19:00”,“19:00-21:00”]}]} name : 必填信息名称writeType: 为填写方式 1: 文本输入框2:单选项框3:多选项框4:数字输入框childList : 二级必填信息选项 说明:1、“name”: “2020-10-27”, 为预计派件日期7天2、时间段范围可选值为固定,分别为:快运产品|重量 [“09:00-12:00”,“12:00-15:00”,“15:00-18:00”]非快运产品时:[ “09:00-11:00”, “11:00-13:00”, “13:00-15:00”, “15:00-17:00”, “17:00-19:00”, “19:00-21:00” ]

2.5.3 补充说明

增值服务扩展自定义字段说明

接入系统 场景名称 extJson 字段名称 数据类型 归属服务代码 说明
CX 增值服务推荐接口中,包装费用中需要包含,包材推荐扩展信息 packjson:{} Object IN67 参考以下内容
参数字段 参数名称 数据类型 备注
payType 限定付款类型 String 1-寄付现结(目前只有寄付现结这一种)
materialInfos 物料信息列表 List 物料信息列表
MaterialInfo 物料信息 参数
materialCode 物料编码 String
materialName 物料全名 String
materialAbbrName 物料简称 String
classifyId 包材分类ID String
packPlanList 计划清单 String
length 长度 Double
width 宽度 Double
height 高度 Double
weight 托寄物重量 Double
packageWeight 包材重量 Double
commodity 托寄物名称 String
classifyName 包材分类名称 String
addedServiceCode 增值服务代码 String
costCode 费用代码 String
priceList 价格列表 List 价格列表
Price 价格 参数
countryCode 国家代码 String
serviceFee 费用值 Double 价格值
currency 币种类型 String
2.6. 请求示例\应用场景(JSON)示例

请求报文:

{
    "businessType": "2",
    "consignedTime": "2020-09-30 17: 01: 48",
    "destAddress": {
        "address": "北京街道西湖路38号首层102号东南铺江博士",
        "city": "广州市",
        "district": "越秀区",
        "province": "广东省"
    },
    "searchPrice": "1",
    "srcAddress": {
        "address": "琶洲街道琶洲蟠龙新街2号保利广场购物中心3层3036号江博士专卖铺",
        "city": "广州市",
        "district": "海珠区",
        "province": "广东省"
    },
    "weight": 1
}
2.7. 返回示例\应用场景(JSON)示例

响应报文:

  • 成功响应:
{
    "success": true,
    "errorCode": "S0000",
    "errorMsg": null,
    "msgData": {
        "deliverTmDto": [
            {
                "businessType": "2",
                "businessTypeDesc": "顺丰特惠",
                "deliverTime": "2020-10-20 18:00:00,2020-10-20 18:00:00",
                "fee": 119,
                "searchPrice": "1",
                "closeTime": null
            }
        ]
    }
}
  • 失败报文-范例1
{
    "success": false,
    "errorCode": "S0001",
    "errorMsg": "非法的JSON格式",
    "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