华南通用下单对接文档


7-预下单接口

预下单接口-速运类API

EXP_RECE_PRE_ORDER
1. 功能描述
  • 客户通过传入地址信息等参数，校验是否能下单成功；
2. 接口定义
2.1. 公共参数
名称 值
接口服务代码 EXP_RECE_PRE_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
2.2. 公共请求参数
序号 参数列表 类型 是否必传 含义
1 已作废 String(64) 是
2 requestID String(40) 是 请求唯一号UUID
3 serviceCode String(50) 是 接口服务代码（COM_RECE_EPS_ORDER）
4 timestamp long 是 调用接口时间戳
5 已作废 String(128) 条件
6 已作废 String 条件
7 msgData String 是 业务数据报文
2.3. 请求参数\
2.3.1 元素 XXXXXX
序号 属性名 类型(约束) 必填 默认值 描述
1 orderId String(64) 是 客户订单号
2 cargoName String(20) 否 拖寄物信息（传入则会校验托寄物品类信息）
3 contactInfoList List 是 收寄双方信息
4 monthlyCard String(20) 否 顺丰月结卡号（传入则会进行高峰管控校验）
5 expressTypeId Number (5) 是 快件产品类别，支持附录《快件产品类别表》的产品编码值，仅可使用与顺丰销售约定的快件产品。
2.3.1.1 元素 Order/List
序号 属性名 类型(约束) 必填 默认值 描述
1 contactType Number (1) 是 地址类型：1，寄件方信息2，到件方信息
2 tel String(20) 否 tel与mobile二选一（如果收寄双方联系方式都有传则会进行电话黑名单防骚扰校验）
3 mobile String(20) 否
4 province String(30) 是 所在省级行政区名称，必须是标准的省级行政区名称如：北京、广东省、广西壮族自治区等；此字段影响原寄地代码识别，建议尽可能传该字段的值。
5 city String(100) 是 所在地级行政区名称，必须是标准的城市称谓 如：北京市、深圳市、大理白族自治州等；此字段影响原寄地代码识别，建议尽可能传该字段的值。
6 county String(30) 否 所在县/区级行政区名称，必须是标准的县/区称谓，如：福田区，南涧彝族自治县、准格尔旗等。
7 address String(200) 是 详细地址，若province/city字段的值不传，此字段必须包含省市信息，避免影响原寄地代码识别，如：广东省深圳市福田区新洲十一街万基商务大厦10楼；若需要生成电子运单，则为必填。
2.4. 公共响应参数
# 属性名 类型(约束) 必填 默认值 描述
1 success String 是 true 请求成功，false 请求失败
2 errorCode String 是 错误编码，S0000成功
3 errorMsg String 是 错误描述
4 msgData String 是 返回的详细数据
2.5. 响应参数\
2.5.1 元素
# 属性名 类型(约束) 必填 描述
1 serviceDate String 是 示例：2021-04-25
2 startTime String 是 示例：2021-04-25 08:30:00
3 endTime String 是 示例：2021-04-25 21:00:00
2.6. 请求示例\应用场景(JSON)示例

请求报文:（msgData字段）:

{
    "orderId": "LP00461749454112",
    "contactInfoList": [{
        "address": "解放一路",
        "city": "福州市,闽清县",
        "contactType": 2,
        "county": "福州市,闽清县",
        "mobile": "13544020940",
        "province": "福建省",
        "tel": "13544020940"
    }, {
        "address": "解放一路",
        "city": "上海市",
        "contactType": 1,
        "county": "闵行区",
        "mobile": "13544020940",
        "province": "上海"
    }],
    "expressTypeId": 1,
    "cargoName": "手机",
    "monthlyCard": "123456789"
}
2.7. 返回示例\应用场景(JSON)示例

响应报文:

  • 成功响应:
{
    "success": true,
    "errorCode": "",
    "errorMsg": ""
    "msgData": [{
        "serviceDate": "2021-04-25",
        "startTime": "2021-04-25 08:30:00",
        "endTime": "2021-04-25 21:00:00"
    }, {
        "serviceDate": "2021-04-26",
        "startTime": "2021-04-26 08:30:00",
        "endTime": "2021-04-26 21:00:00"
    }, {
        "serviceDate": "2021-04-27",
        "startTime": "2021-04-27 08:30:00",
        "endTime": "2021-04-27 21:00:00"
    }]
}
  • 失败响应：
{
   "apiErrorMsg": "",
   "apiResponseID": "00016AD45F84743F9486F3154DC9A03F",
   "apiResultCode": "A1000",
   "apiResultData": 
"{\"errorMessage\":\"请求失败，请重试\",\"success\":false,\"errorCode\":\"09020501\"}"
}
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 业务异常代码
错误代码 错误中文描述 错误英文描述 【处理建议】
1010 寄件地址不能为空 Shipper‘s address is required. address不能为空
1011 寄件联系人不能为空 Shipper‘s contract name is required. contact不能为空
1012 寄件电话不能为空 Shipper‘s telephone number is required. mobile和tel不能都为空
1014 到件地址不能为空 Receiver‘s adress is required. address不能为空
1015 到件联系人不能为空 Receiver‘s contact name is required. contact不能为空
1016 到件电话不能为空 Receiver‘s telephone number is required. mobile和tel不能都为空
1020 出口件邮编不能为空 Postal code is required for International shipments. postCode不能为空
1023 拖寄物品名不能为空 Commodity name is required. cargoDetails下面的name不能为空
1028 出口件时，拖寄物数量不能为空 Commodity quantity is required for international shipments. cargoDetails下面的count不能为空
1038 出口件声明价值不能为空 The declared value is required for International shipments. cargoDeclaredValue不能为空
6126 月结卡号不合法 Invalid credit account number. monthlyCard月结卡号必须为10位数字
6127 增值服务名不能为空 AVS name is required. serviceList下面的name为空
6128 增值服务名不合法 Invalid AVS name. serviceList 下面name传值不正确
6130 体积参数不合法 Invalid Volume Parameters volume传参不正确
6138 代收货款金额传入错误 COD amount data error. serviceList中name为COD 对应的value为数字
6139 代收货款金额小于0错误 Error! COD amount is less than 0. serviceList中name为COD 对应的value必须大于0
6200 国际件寄方邮编不能为空 The shipper postal code is required for International shipment. postCode不能为空
6201 国际件到方邮编不能为空 The receiver postal code is required for International shipment. postCode不能为空
6202 国际件货物数量不能为空 The cargo quantity is required for International shipment. cargoDetails下面的count不能为空
6203 国际件货物单位不能为空 The cargo unit is required for International shipment. cargoDetails下面的unit不能为空
6204 国际件货物单位重量不能为空 The cargo unit weight is required for International shipment. cargoDetails下面的weight不能为空
6205 国际件货物单价不能为空 The cargo unit value is required for International shipment. cargoDetails下面的amount不能为空
6206 国际件货物币种不能为空 The cargo currency is required for International shipment. cargoDetails下面的currency不能为空
6207 国际件原产地不能为空 Origin code is required for International shipment. cargoDetails下面的sourceArea不能为空
8016 重复下单 Duplicated order ID. orderId不能重复
8027 不存在的业务模板 Business template does not exist. bizTemplateCode传入了不存在的模板 或者传空了
8067 超过最大能申请子单号数量 Exceed the maximum number of the available sub waybills. 下单接口默认最大申请子单号数量我307个
8096 您的预约超出今日营业时间，无法上门收件。 sendStartTm传工作时间。或者isDocall传0
8114 传入了不可发货的月结卡号 联系销售经理增加该月结卡号下单权限
8117 下单包裹不能大于307个 下单接口默认最大申请子单号数量我307个
8119 月结卡号不存在或已失效 传入的monthlyCard不存在或已失效
8194 跨境件必须包含申明价值和币别 跨境件申明价值（consValue）和申明价值币别（consValueCurrencyCod）e必须要传
8196 信息异常 收件或者寄件电话号码黑名单
8247 运单号不合法 请核实运单号是否是顺丰运单号（注意顺丰生产环境 测试环境 丰桥上面的单不能混用）
8053 目的地不在定时派送服务范围内 到件地址不支持定时派送。可以去掉定时派送（IN26）增值服务
8052 原寄地不在定时派送服务范围内 寄件地址不支持定时派送。可以去掉定时派送（IN26）增值服务
8051 定时派送不在时效范围内，下单失败 传入的时间不在时效范围内，可以根据返回响应的时间段来传值
8179 卡号下未查到关联相应协议 需要找销售签订对应的产品协议
8177 类似 （正值运力高峰期，普通会员（非会员）的寄件通道预约已满，敬请谅解） 提示语组成 BPS：策略编号 高峰管控
20012 定时派送服务不支持重量超过300KG的快件 totalWeight不能超过300kg
20011 产品与定时派送服务时间段不匹配 修改TDELIVERY增值服务value1传值
8256 部分快件产品不支持到付和寄付现结，请调整付款方式后下单 付款方式payMethod传1 3 并且monthlyCard需要传值
20035 托寄物违禁品不可收寄 修改托寄物cargoDetails的name
20036 适用产品不满足 更改产品expressTypeId重新下单，如不行，请联系顺丰销售业务经理处理
8057 快件类型为空或未配置 expressTypeId不正确，请参看《快件产品类别表》
20003 联系人格式有误 contactInfoList不可为空，收寄双方信息不可为空，contactType必须在枚举的范围；
S0008 地址不可达 寄方或到方地址不可达；
8040 寄方地址错误 省市区详细地址不可为空；
8041 到方地址错误 省市区详细地址不可为空；
8177 高峰管控 延时管控策略 更换下单时间；
8216 黑名单验证 骚扰用户信息反馈异常码寄件方 客户设置了寄件方防骚扰号码，确认无误可以点击解除。
8217 黑名单验证 骚扰用户信息反馈异常码 到件方 客户设置了到件方防骚扰号码，确认无误可以点击解除。

速运类接口业务相关错误码

页面列表

ITEM_HTML