华南通用下单对接文档


1-产品推荐接口

产品推荐接口-速运类API

EXP_RECE_PSDS_PRODUCT_RECOMMEND

1. 功能描述
  • 此功能主要是提供产品推荐的查询。
2. 接口定义
2.1. 公共参数
名称
接口服务代码 EXP_RECE_PSDS_PRODUCT_RECOMMEND
生产环境地址 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 expiresIn Number 条件 已作废,使用OAuth2方式认证时必填 获取方法参考:OAuth2认证说明
7 msgData String 业务数据报文
2.3. 请求参数\ /ProductRecommendReq
# 参数字段 参数名称 是否必填 数据类型 备注
1 traceId 溯源ID String 用于数据埋点追踪,必须唯一,推荐使用UUID,CX会员ID
2 waybillNo 订单号/运单号 String 如:SF955536546
3 srcProvince 原寄地省 String 如:广东省
4 srcCity 原寄地市 String 如:深圳市
5 srcCounty 原寄地区 String 如:南山区
6 destProvince 到方地址省 String 如:广东省
7 destCity 到方地址市 String 如:深圳市
8 destCounty 到方地址区 String 如:南山区
9 sendTime 寄件时间/预约上门时间 String 格式为:yyyy-MM-dd HH:mm:ss
10 orderTime 下单时间 String 格式为:yyyy-MM-dd HH:mm:ss,默认系统当前时间
11 weight 重量 Double 如:3.5 重量单位为kg
12 length Double 如:74 单位为cm
13 width Double 如:20.5 单位为cm
14 height Double 如:3.5 单位为cm
15 commodityNameList 托寄物名称 List 支持多个,如:[海鲜,水果]定义
16 paymentTerms 付款方式 String 1.寄付; 2.到付;3.寄转第三方;4.到转第三方
17 monthlyCard 月结账号 String 如:7551234567
18 totalNum 总件数 Integer 如:200
19 phoneNumber 手机号码 String 付款方式为寄付或寄转第三方付传入寄方电话,若为到付传收方电话;
20 srcAddress 原寄地详细地址 String 寄件地址
21 destAddress 目的地详细地址 String 收件地址
22 importDeclarationMethod 入口报关方式 String 仅国际在使用,报关方式如下(代码,名称):1:简易报关,2:正式报关,3:海运报关,4:个人物品,5:简报销售,6:简报样品,7:跨境直邮,8:跨境保税,9:个人行李,10:自清关
23 exportDeclarationMethod 出口报关方式 String 仅国际在使用,报关方式如下(代码,名称):1:简易报关,2:正式报关,3:海运报关,4:个人物品,5:简报销售,6:简报样品,7:跨境直邮,8:跨境保税,9:个人行李,10:自清关
24 declaredValue 申报价值 Double 申报价值
25 declaredCurrency 申报币种 String 申报币种
2.4. 公共响应参数
# 属性名 类型(约束) 必填 默认值 描述
1 success String true 请求成功,false 请求失败
2 errorCode String 错误编码,S0000成功
3 errorMsg String 错误描述
4 msgData String 返回的详细数据
2.5. 响应参数\
参数字段 参数名称 数据类型 备注
1 productList 产品列表 List 推荐产品列表
2 fastigiumControlStrategyList 高峰管控策略 List 产品高峰期管控策略信息

2.5.1 元素 ProductDto

# 参数字段 参数名称 数据类型 备注
1 recommendProductType 产品推荐类型 Integer 1:协议产品 2:基础产品 3:其他产品
2 sortNo 排序号 Integer 1/2/3/4/5/6……,序号可能重复或不连续;若使用,按升序排序即可;
3 productCode 产品代码 String 如:S1
4 expressType bsp产品编码 String 如:1,2
5 reachTimeType 时效类型代码 String 如:T4
6 expressContent 快件内容代码 String 如:C201
7 businessType 业务类型代码 String 如:B2
8 productName 产品名称 String 如:顺丰标快
9 productType 产品类型 String 如:1便利店,2医药,3时效,4高铁,5冷运,6快运,7国际,8特惠
10 totalFee 总费用 Double 如:21.5
11 currency 币种 String 如:CNY
12 weight 计费重量 Double 如:1.5(重量KG)
13 reachTime 时效 String 格式yyyy-MM-dd HH:mm
14 cutOffTime 截单时间 String 只有ptcs有才不为空。格式HHmm。
15 suburbFlg 是否郊区件 Boolean true:郊区件false:不是郊区件null:pvs返回没有区分出来,一般不会出现
16 reverseLogistics 是否适用逆向物流 String 0:否,1:是
17 deliverySfbox 是否允许投丰巢柜、便利店 String 0:否,1:是
18 overtimeRefund 是否支持超时退费 String 0:否,1:是
19 specialCommodityMsg 特殊托寄物提示语 String 如:易腐生鲜类时效超2D,有损坏风险,请谨慎选择产品。
20 clearanceOfGoods 是否需要报关材料 String 0:否,1:是
21 productLayered 产品分层 String 1:高端产品目前只有1
22 freight 运费 Double 运费,固定返回个性化运费,透传pvs
23 stdFreight 标准运费 Double 标准运费,无客户轻抛系数、客户报价、客户计价浮动,透传pvs
24 initialFreight 原运费 Double 原运费(未计算渠道优惠时的个性化运费),透传pvs
25 totalServiceFee 合计增值服务费 Double 合计增值服务费,透传pvs
26 serviceFeeList 增值费明细 Array 增值费明细,参照2.6,透传pvs目前有如下增值服务 燃油附加费:IN15 散单促销(区域优惠费):IN106 超长超重服务费:IN23 大件入户服务费:IN98 丰巢超重费:OS04 快运渠道优惠费:OS06 冷运提货费:IN73 冷运送货费:IN74 安心保包装减免:OS05
27 selfMailingFee 自寄优惠费 Double 自寄优惠费,透传pvs
28 selfTakeFee 自取优惠费 Double 自取优惠费,透传pvs
29 otherFee 其他费用 Double 其他费用,透传pvs
30 priceDetail 计价规则 String 计价规则,透传pvs
31 productDisplayCode 展示名称代码 String 如:SER-1
32 productDisplayName 产品展示名称 String 如:顺丰特快(优)
33 waybillLabelCode 面单标签代码 String 如:Tab-1
34 waybillLabelName 面单标签名称 String 如:特快(优)

2.5.2 元素 FastigiumControlStrategy

# 参数字段 参数名称 数据类型 备注
1 productCode 产品代码 String 如:S1
2 controlStrategy 管控策略 String 管控策略0:不管控1:延时管控2:错峰管控3:加价管控4.温馨提示
3 notificationMsg 管控提示 String 管控提示(随language变化)

2.5.3 增值费详细

字段 类型 说明
serviceCode String 增值服务代码
serviceFee Double 增值服务费
stdServiceFee Double 标准增值服务费
weight Double 计费重量
isGuide boolean 是否指导价格
serviceName String 服务名称
collectionAmount Double 代收货款金额,代收货款时有值,若目的地币种与服务费币种不一 致,会转换汇率,否则等于传入值
codExchangeRate Double 代收货款汇率,代收货款时有值,目的地国家币种转换服务费币种的汇率
2.6. 请求示例\应用场景(JSON)示例

请求报文:

{
    "srcProvince":"广东省",
    "srcCity":"深圳市",
    "srcCounty":"南山区",
    "destProvince":"广东省",
    "destCity":"深圳市",
    "destCounty":"龙岗区",
    "paymentTerms":"1",
    "destAddress":"广东省-深圳市-龙岗区得宜一街路与龙岗大道交叉口南50米牛始埔村3区",
    "weight":5,
    "srcAddress":"广东省-深圳市-南山区南新路前海枫叶大厦1001室",
    "commodityNameList":[
        "文件",
        "苹果"
    ],
    "sendTime":"2021-06-18 14:47:00",
    "phoneNumber":"13728715806",
    "monthlyCard":"7550839589",
    "totalNum":2
}
2.7. 返回示例\应用场景(JSON)示例

响应报文:

  • 成功响应:
{
    "success": true,
    "errorCode": "S0000",
    "errorMsg": null,
    "msgData": []
}
  • 失败响应
{
    "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