快递可达性判断

京东承运商停运/超区查询

一、接口名称

京东承运商停运/超区查询

路径：POST https://kf.fw199.com/gateway/jd/alpha/waybill/outagequery

二、请求参数

请求方式为 POST，Content-Type: application/x-www-form-urlencoded。

二（一）、公共参数

参数名称	类型	是否必填	示例值	描述
appid	String	是	合作伙伴 AppId	蜂巢分配的 appid
timestamp	String	是	1782991878	当前 Unix 时间戳（秒）
sign	String	是	xxxxx	签名，算法见蜂巢签名规范
seller_nick	String	是	98731190	京东店铺 seller_nick（授权店铺标识）
sysid	String	是	404	联系客服
request_data	String	是	见下方 JSON	停运查询业务参数，JSON 字符串

二（二）、request_data 字段说明

request_data 为 JSON 字符串，字段如下：

参数名称	类型	是否必填	示例值	描述
providerCode	String	是	YTO	承运商编码，取自 `jingdong.ldop.alpha.provider.query` 返回的 `providerCode`
providerId	Number	否	463	承运商 ID，取自 `jingdong.ldop.alpha.provider.query` 返回的 `id`
provinceId	Number	是	17	国标省/直辖市 ID（民政部）
provinceName	String	否	湖北省	国标省/直辖市名称
cityId	Number	是	1381	国标市 ID
cityName	String	否	武汉市	国标市名称
countryId	Number	是	50718	国标区/县 ID
countryName	String	否	洪山区	国标区/县名称
countrysideId	Number	否	53772	国标乡镇/街道 ID
countrysideName	String	否	关东街道	国标乡镇/街道名称
address	String	是	湖北省武汉市洪山区关东街道关山大道591号…	详细地址（含省市县的完整地址）

request_data 示例：

{
  "providerCode": "YTO",
  "providerId": 463,
  "provinceId": 17,
  "provinceName": "湖北省",
  "cityId": 1381,
  "cityName": "武汉市",
  "countryId": 50718,
  "countryName": "洪山区",
  "countrysideId": 53772,
  "countrysideName": "关东街道",
  "address": "湖北省武汉市洪山区关东街道关山大道591号中建三局三公司铁箕山小区"
}

三、请求示例代码

Java

Utils.Sign、doHttpRequest 为项目内统一封装，此处仅展示业务参数组装

@Test
public void jdAlphaWaybillOutageQuery() throws Exception {

    String sellerNick = "98731190";
    String apiUrl = Config.GatewayUrl + "/jd/alpha/waybill/outagequery";

    String requestData = "{"
        + "\"providerCode\":\"YTO\","
        + "\"providerId\":463,"
        + "\"provinceId\":17,"
        + "\"provinceName\":\"湖北省\","
        + "\"cityId\":1381,"
        + "\"cityName\":\"武汉市\","
        + "\"countryId\":50718,"
        + "\"countryName\":\"洪山区\","
        + "\"countrysideId\":53772,"
        + "\"countrysideName\":\"关东街道\","
        + "\"address\":\"湖北省武汉市洪山区关东街道关山大道591号中建三局三公司铁箕山小区\""
        + "}";

    Map<String, String> data = new HashMap<>();
    data.put("appid", Config.AppId);
    data.put("seller_nick", sellerNick);
    data.put("sysid", "404");
    data.put("request_data", requestData);
    Long timestamp = System.currentTimeMillis() / 1000;
    data.put("timestamp", timestamp.toString());
    data.put("sign", Utils.Sign(data, Config.AppSecret));

    String result = doHttpRequest(apiUrl, data);
    System.out.println("result:" + result);
}

四、返回结果

四（一）、成功示例

最外层 code=0 表示蜂巢调用成功；data.returnType.statusCode=0 表示京东停运查询业务成功。

{
  "code": 0,
  "message": "ok",
  "data": {
    "code": "0",
    "request_id": "3503654.39587.17829919766523634",
    "returnType": {
      "statusMessage": "调用成功",
      "statusCode": 0
    }
  },
  "trace_id": "25be0c4e-0953-4cad-acad-78647b528364"
}

data 字段说明：

字段	类型	描述
code	String	京东响应码，`"0"` 表示正常
request_id	String	京东请求 ID
returnType	Object	停运查询结果
returnType.statusCode	Number / String	业务状态码，`0` 表示成功（如未停运）
returnType.statusMessage	String	业务状态描述，如「调用成功」「调用成功（未停运）」

说明

最外层 code=0 表示蜂巢接口调用成功；非 0 为失败，原因见 message。
providerCode 建议先调用蜂巢「获取承运商列表」接口（/gateway/jd/alpha/getprovider）获取。