订单收派范围查询

客户系统通过此接口向顺丰系统发送主动的筛单请求,用于判断客户的收、派地址是否属于顺丰的收派范围。

一、请求参数

POST https://kf.fw199.com/gateway/sfexpress/order/filter

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

一（一）、参数request_data 的说明

#	属性名	类型(约束)	必填	默认值	描述
1	filterType	Number(1)	是	1	筛单类别:1:自动筛单(系统根据地址库进行判断,并返回结果,系统无法检索到可派送的将返回不可派送)2:可人工筛单(系统首先根据地址库判断,如果无法自动判断是否收派,系统将生成需要人工判断的任务,后续由人工处理,处理结束后,顺丰可主动推送给客户系统)
2	orderId	String	否		客户订单号
3	monthlyCard	String	否		月结卡号
4	contactInfos	List	否		地址信息（详细参看下2.4.2.2）

一（二）、元素 contactInfos/FilterAddrInfoDto

#	属性名	类型(约束)	必填	默认值	描述
1	contactType	Integer	否		地址类型 1:寄件方 2:到件方
2	tel	String	否		联系电话
3	country	String	否		国家或地区代码 2位
4	province	String	否		省级行政区名称
5	city	String	否		地级行政区名称
6	county	String	否		县/区级行政区名称
7	address	String	否		详细地址
8	postCode	String	条件		邮编，跨境件必填

二、请求示例代码

Java

/**
     * 订单筛选接口
     * @throws Exception
     */
    @Test
    public void filterOrder() throws Exception {

        String result ="";

        // dealType：2表示取消
        String jsonData  = "[{" +
                "\"contactInfos\": [{" +
                "\"address\": \"浙江省深圳市南山区粤海街道创智天地大厦B栋27楼南区\"," +
                "\"city\": \"深圳市\"," +
                "\"contactType\": 1," +
                "\"country\": \"中国\"," +
                "\"county\": \"\"," +
                "\"province\": \"广东省\"," +
                "\"tel\": \"4001118851\"" +
                "}, {" +
                "\"address\": \"南朗镇翠亨村101\"," +
                "\"city\": \"中山市\"," +
                "\"contactType\": 2," +
                "\"country\": \"中国\"," +
                "\"county\": \"\"," +
                "\"province\": \"广东省\"," +
                "\"tel\": \"15888888111\"" +
                "}]," +
                "\"filterType\": 1 " +
                "}]";

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

        //业务参数
        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": "00017A8A1737A83FED7F51BD7733F13F",
        "apiResultCode": "A1000",
        "apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":[{\"orderId\":null,\"filterResult\":2,\"originCode\":\"755\",\"destCode\":\"760\",\"remark\":null}]}"
    },
    "trace_id": "SoSQonmPoFRCkHAgi98V"
}

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

四、元素 OrderFilterResponse

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

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

#	属性名	类型(约束)	必填	默认值	描述
1	orderId	boolean	是		客户订单号
2	filterResult	Integer	是		筛单结果：1：人工确认2：可收派3：不可以收派4 : 地址无法确认当filter_type=1时，不存在1值
3	originCode	String	条件		原寄地区域代码，如果可收派，此项不能为空
4	destCode	String	条件		目的地区域代码，如果可收派，此项不能为空
5	remark	String	条件		如果filter_result=3时为必填，不可以收派的原因代码：1：收方超范围2：派方超范围3：其它原因