路由查询

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

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

1 )根据顺丰运单号查询：查询请求中提供接入编码与运单号，验证接入编码下绑定的月结卡号与请求运单号的归属关系，系统只返回具有正确归属关系的运单路由信息。

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

3. 根据运单号+运单对应的收寄人任一方电话号码后4位(参数checkPhoneNo中传入)查询,系统校验信息匹配将返回对应运单路由信息。若一次性查多个路由，checkPhoneNo传入多个电话号码后4位，用英文逗号隔开，作为一个字符串

一、请求参数

POST https://kf.fw199.com/gateway/sfexpress/routes/search

参数名	类型	说明	示例
appid	String	合作伙伴AppId	uwkahf@jfs92
timestamp	String	当前时间戳
request_data	String	json格式的业务参数	见下表1.1
client_code	String	顺丰的客户编码
check_word	String	顺丰的校验码
sign	String	接口签名	如何计算生成见示例代码

一（一）、参数request_data 的说明

#	属性名	类型(约束)	必填	默认值	描述
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	checkPhoneNo	String(30)	否		电话号码验证
6	referenceNumber	String(4000)	否		参考编码（目前针对亚马逊客户，由客户传）

二、请求示例代码

Java

/**
     * 路由查询
     * @throws Exception
     */
    @Test
    public void searchRouters() throws Exception {

        String result ="";

        // dealType：2表示取消
        String jsonData  = "{" +
                "\"language\": \"0\"," +
                "\"trackingType\": \"2\"," +
                "\"trackingNumber\": [\"QIAO-20200605-003\"]," +
                "\"methodType\": \"1\"" +
                "}";

        CloseableHttpClient httpclient = HttpClients.createDefault();
        HttpPost httpPost = new HttpPost( Config.SFExpressSearchRoutersUrl );

        //业务参数
        Map<String, String> data = new HashMap<String, String>();
        data.put("appid",  Config.AppId);
        data.put("request_data", jsonData);
        data.put("client_code",  Config.SFClientCode);
        data.put("check_word",  Config.SFCheckWord);
        Long timestamp = System.currentTimeMillis() / 1000;
        data.put("timestamp", timestamp.toString());

        // 参数签名
        data.put("sign", Utils.Sign(data,Config.AppSecret));
        List<BasicNameValuePair> params = new ArrayList<BasicNameValuePair>();
        for (Map.Entry<String, String> entry : data.entrySet()) {
            params.add(new BasicNameValuePair(entry.getKey(), entry.getValue()));
        }
        //发起POST请求
        try {
            httpPost.setEntity(new UrlEncodedFormEntity(params, "UTF-8"));
            HttpResponse httpResponse = httpclient.execute(httpPost);
            if (httpResponse.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
                result =  EntityUtils.toString(httpResponse.getEntity());
            } else {
                result =  ("doPost Error Response: " + httpResponse.getStatusLine().toString());
            }
        } catch (Exception e) {
            e.printStackTrace();

        }

        System.out.println(result);

    }

三、返回结果

{
    "code": 0,
    "message": "ok",
    "data": {
        "apiErrorMsg": "",
        "apiResponseID": "00017A8A1F850F3FEDB3F554A3D05D3F",
        "apiResultCode": "A1000",
        "apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":{\"routeResps\":[{\"mailNo\":null,\"routes\":[],\"orderId\":\"QIAO-20200605-003\"}]}}"
    },
    "trace_id": "gU1K3Z1AyX6gEbBE99oH"
}

说明： code为0表示成功，非0为失败，message会包含失败原因。

四、元素 apiResultData

#	属性名	类型(约束)	必填	默认值	描述
1	success	boolean	是		返回状态 true/false
2	errorCode	Integer	条件		错误代码
3	errorMsg	String	条件		错误详细信息
4	msgData	Object	条件		如果success为true，这个字段代表筛单结果；Success为false时，此字段为空

四（一）、返回参数msgData说明

#	属性名	类型(约束)	必填	默认值	描述
1	routeResps	List	是		顺丰运单号对应的路由详情（列表）

四（二）、元素 QuerySFRouteResponse/msgData/routeResps

#	属性名	类型(约束)	必填	默认值	描述
1	mailNo	String	是		顺丰运单号
2	routes	List	是		路由信息（列表）

四（三）、元素 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)	是		路由节点操作码

注意事项:

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

目前支持中文简体,中文繁体和英文，返回语言与下单一致，若需返回中文繁体或英文，下单需为对应语言。

可在文档中心查看路由节点信息操作码。

4)定制路由查询须与顺丰商务人员沟通，客户可基于顺丰所有路由节点（列表可从顺丰商务人员处获取）定制所需的路由节点及其具体描述与操作码。

四（四）、路由信息操作码

操作码(opCode)	操作名称(opName)
30	快件在【XXX营业点】已装车,准备发往 【XXX集散中心】
31	快件到达 【XXX集散中心】
33	派件异常原因
3036	快件在XXX ,准备送往下一站
44	正在派送途中,请您准备签收(派件人:XXX,电话:XXX)
50	顺丰已收件
70	由于XXX原因 派件不成功
80	已签收,感谢使用顺丰,期待再次为您服务
8000	在官网”运单资料&签收图”,可查看签收人信
130	快件到达顺丰店/站
123	快件正送往顺丰店/站
607	代理收件
99	应客户要求,快件正在转寄中
648	快件已退回/转寄,新单号为: XXX