10-时效标准及价格查询接口

时效标准及价格查询接口-速运类API

EXP_RECE_QUERY_DELIVERTM

---

1. 功能描述

• 客户可通过接口查询从特定原寄地寄特定目的地的时效和价格。

2. 接口定义

2.1. 公共参数

名称	值
接口服务代码	EXP_RECE_QUERY_DELIVERTM
生产环境地址	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. 请求参数\

#	属性名	类型（约束）	必填	默认值	描述
1	businessType	String	Y		快件产品：可以为空，为空时查询默认时效对应的产品列表。不为空时以数字代码业务类型，例如：1：表示“”2：表示“顺丰特惠”5：表示“顺丰次晨”6：表示“即日件
2	weight	Double	N		货物总重量，包含子母件，单位千克，精确到小数点后2位，如果提供此值，必须>0。
3	volume	Double	N		货物的体积（长、宽、高分别以厘米为单位计算体积），精确到小数点后2位。
4	consignedTime	String	N		寄件时间，格式为YYYY-MM-DD HH24:MM:SS，示例2013-12-27 17:54:20。
5	searchPrice	String	N		1：表示查询含价格的接口0：表示查询不含价格的接口 备注：限制只能为0,1或者不传searchPrice，不可以为空,null
6	destAddress	Obj	Y		目的地信息
7	srcAddress	Obj	Y		原寄地信息

2.3.1 元素 destAddress

#	属性名	类型（约束）	必填	默认值	描述
1	province	String(30)	条件		目的地所在省份，字段填写要求：必须是标准的省名称称谓 如：广东省; 如果是直辖市，请直接传北京、上海等，如果字段code为空时为必填。
2	city	String(100)	条件		目的地所在城市，必须是标准的城市称谓 如：深圳市，如果字段code为空时为必填。
3	district	String(100)	N		目的地所在县/区，必须是标准的县/区称谓，示例：“福田区”。
4	address	String(450)	N		目的地详细地址，此详细地址需包含省市信息，以提高地址识别的成功率，示例：“广东省深圳市福田区新洲十一街万基商务大厦10楼”。
5	code	String(30)	条件		目的地区域代码，如果填写了此项，则查询时忽略省市区具体地址，如果不填此项，则综合省市区具体地址识别区域代码，字段province或city为空时为必填，示例：020、755。

2.3.2 元素srcAddress

#	属性名	类型（约束）	必填	默认值	描述
1	province	String(30)	条件		原寄地所在省份，字段填写要求：必须是标准的省名称称谓 如：广东省如果是直辖市，请直接传北京、上海等，与字段city同时存在时忽略字段address如果字段code与字段address皆为空时为必填。
2	city	String(100)	条件		原寄地所在城市，必须是标准的城市称谓 如：深圳市，与字段province同时存在时忽略字段address，如果字段code与字段address皆为空时为必填。
3	district	String(100)	否		原寄地所在县/区，必须是标准的县/区称谓，示例：“福田区”。
4	address	String(450)	条件		原寄地详细地址，此详细地址需包含省市信息，以提高地址识别的成功率，示例：“广东省深圳市福田区新洲十一街万基商务大厦10楼”，字段code为空且字段province或字段city其一为空时为必填。
5	code	String(30)	条件		原寄地区域代码，如果填写了此项，则忽略字段address，字段province及字段city。字段address为空且字段province或字段city其一为空时为必填，示例：020、755。

2.4. 公共响应参数

#	属性名	类型(约束)	必填	默认值	描述
1	success	String	是		true 请求成功，false 请求失败
2	errorCode	String	是		错误编码，S0000成功
3	errorMsg	String	是		错误描述
4	msgData	String	是		返回的详细数据

2.5. 响应参数\

#	属性名	类型（约束	必填	默认值	描述
1	businessType	String			快件产品；
2	businessTypeDesc	String			快件产品描述：
3	deliverTime	String			承诺时间；
4	fee	Double			价格；
5	searchPrice	String			是否查询价格（1,返回价格；0，不返回价格）；
6	closeTime	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数据类型错误