华南通用下单对接文档


5-路由查询接口

路由查询接口接口-速运类API

EXP_RECE_SEARCH_ROUTES

1. 功能描述

客户可通过此接口查询顺丰运单路由,顺丰会在响应Json报文返回当时点要求的全部路由节点信息。

此路由查询接口支持三类查询方式:

  • 1)根据顺丰运单号查询:查询请求中提供接入编码与运单号,验证接入编码与所有请求运单号的归属关系,系统只返回具有正确归属关系的运单路由信息。

  • 2)根据客户订单号查询:查询请求中提供接入编码与订单号,验证接入编码与所有请求订单号的归属关系,对于归属关系正确的订单号,找到对应的运单号,然后返回订单对应运单号的路由信息。适用于通过下单的客户订单。

  • 3)根据运单号+运单对应的收寄人任一方电话号码后4位(参数checkPhoneNo中传入)查询,系统校验信息匹配将返回对应运单路由信息。一次性查多个路由,checkPhoneNo传入多个电话号码后4位,用英文逗号隔开,作为一个字符串
2. 接口定义
2.1. 公共参数
名称
接口服务代码 EXP_RECE_SEARCH_ROUTES
沙箱环境地址 https://sz-mix.sit.sf-express.com/backend/std/service/{hnCustomerCode} 测试{hnCustomerCode}统一为11aeea6bdd7fbae1
生产环境地址 https://sz-mix.sf-express.com/backend/std/service/{hnCustomerCode} 生产{hnCustomerCode}请向大客获取。
批量交易 最多10个tracking_number
接口类型 接入
报文类型 JSON
2.2. 公共请求参数
序号 参数列表 类型 是否必传 含义
1 已作废 String(64)
2 requestID String(40) 请求唯一号UUID
3 serviceCode String(50) 接口服务代码(EXP_RECE_SEARCH_ROUTES)
4 timestamp long 调用接口时间戳
5 已作废 String(128) 条件
6 已作废 String 条件
7 msgData String 业务数据报文
2.3. 请求参数\
# 属性名 类型(约束) 必填 默认值 描述
1 language Number(1) 0 返回描述语语言0:中文 1:英文 2:繁体
2 trackingType Number(2) 1 查询号类别:1:根据顺丰运单号查询,trackingNumber将被当作顺丰运单号处理2:根据客户订单号查询,trackingNumber将被当作客户订单号处理
3 trackingNumber List 查询号:trackingType=1,则此值为顺丰运单号如果trackingType=2,则此值为客户订单号
4 methodType Number(1) 1 路由查询类别:1:标准路由查询2:定制路由查询
5 referenceNumber String(4000) 参考编码(目前针对亚马逊客户,由客户传)
6 checkPhoneNo String(30) 电话号码验证
2.4. 公共响应参数
# 属性名 类型(约束) 必填 默认值 描述
1 success String true 请求成功,false 请求失败
2 errorCode String 错误编码,S0000成功
3 errorMsg String 错误描述
4 msgData String 返回的详细数据
2.5. 响应参数\
序号 参数列表 类型 是否必传 含义
1 routeResps List 顺丰运单号对应的路由详情(列表)
2.5. 1元素 QuerySFRouteResponse/msgData/routeResps
序号 参数列表 类型 是否必传 含义
1 mailNo String 顺丰运单号
2 routes List 路由信息(列表)
2.5. 2元素 QuerySFRouteResponse/msgData/routeResps/routes
序号 参数列表 类型 是否必传 含义
1 acceptTime Date 路由节点发生的时间,格式:YYYY-MM-DD HH24:MM:SS,示例:2012-7-30 09:30:00
2 acceptAddress String(100) 路由节点发生的地点
3 remark String(150) 路由节点具体描述
4 opcode String(20) 路由节点操作码

注意事项:

  • 同一批次顺丰运单路由信息必须为同一语言。

  • 目前支持中文简体,中文繁体和英文。

  • 可在服务与支持—>业务文档查看。

  • 定制路由查询须与顺丰商务人员沟通,客户可基于顺丰所有路由节点(列表可从顺丰商务人员处获取)定制所需的路由节点及其具体描述与操作码。
2.6. 请求示例\应用场景(JSON)示例

请求报文:

{
    "language": "0",
    "trackingType": "1",
    "trackingNumber": ["444003077898", "441003077850"],
    "methodType": "1"
}
2.7. 返回示例\应用场景(JSON)示例

响应报文:

  • 成功响应:
{
    "apiResponseID": "000173271968963FA47C03E68000103F",
    "apiErrorMsg": "",
    "apiResultCode": "A1000",
    "apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":{\"routeResps\":[{\"mailNo\":\"SF1011603494291\",\"routes\":[{\"acceptTime\":\"2019-05-09 10:11:26\",\"acceptAddress\":\"深圳\",\"opcode\":\"50\",\"remark\":\"已派件\"},{\"acceptTime\":\"2019-05-09 18:11:26\",\"acceptAddress\":\"深圳\",\"opcode\":\"80\",\"remark\":\"已签收\"}]}]}}"
}
  • 失败报文-范例1
{

    "succ": "fail"
}
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 描述 【处理建议】
9 6133 路由查询类别不合法 method_type传 1 2
10 8013 未传入查询单号 tracking_number没有传值
11 8003 查询单号超过最大限制 一次最多查询10个单号

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

页面列表

ITEM_HTML