取号-获取快递单号

ISV、POP后台推送运单接口，即获取快递单号.

说明：
权限对应： ISV、POP后台推送运单接口

1.请求参数:

请求URL:

POST https://kf.fw199.com/gateway/jd/alpha/waybill/receive

公共参数

业务参数

content的各字段含义参见: https://cloud.jdl.com/#/open-business-document/api-doc/207/464,

request_data的报文示例,注意是一个集合:

1、 明文订单取号的示例

[{
    "waybillType":1,
    "waybillCount":1,
    "providerCode":"SF",
    "platformOrderNo":"255919279479",
    "vendorCode":"12412981",
    "vendorName":"依迪筱童装旗舰店",
    "vendorOrderCode":"9999",
    "salePlatform":"0010001",
    "childMotherOrder":true,
    "fromAddress":{
        "provinceName":"上海",
        "cityName":"上海市",
        "countrysideName":"浦东新区",
        "address":"商城路738号",
        "contact":"王小姐",
        "phone":"13601812022",
        "mobile":"13601812022"
    },
    "toAddress":{
        "provinceId":12,
        "provinceName":"XXX",
        "cityId":232,
        "cityName":"YYY",
        "countryId":1232,
        "countryName":"ZZZ",
        "countrysideId":10098,
        "countrysideName":"CCC",
        "address":"北京市海淀区XXX小区",
        "contact":"李小溪",
        "phone":"010-19999999",
        "mobile":"18988882228"
    },
    "weight":0,
    "volume":0,
    "payType":0,
    "shouldPayMoney":0,
    "needGuarantee":false,
    "settlementCode":"0210603333",
    "expressPayMethod":"1",
    "expressType":"1",
    "promiseTimeType":0,
    "guaranteeMoney":0
}
]

取号入参数字段中，几个核心字段说明

2、 密文订单取号的示例

主要是收件人信息toAddress字段的构建，其脱敏字段和密文字段值均来自增强型订单列表接口或订单详情接口。建议3中的oaid模式取号。

[{
    "waybillType":1,
    "waybillCount":1,
    "providerCode":"ZGYZZHDD",// 通过获取签约的快递公司接口https://doc.fw199.com/docs/h7b/jd-provider-sign-success获取
    "platformOrderNo":"282788xxxx",
    "vendorCode":"10424796",
    "vendorName":"尚XX旗舰店",
    "vendorOrderCode":"9999",
    "salePlatform":"0010001",
    "childMotherOrder":true,
    "fromAddress":{
        "provinceName":"福建省",
        "cityId":350500,
        "cityName":"泉州市",
        "countrysideName":"安溪县",
        "address":"中国家居工艺城",
        "contact":"小廖",
        "phone":"18888888888",
        "mobile":"18888888888"
    },
    "toAddress":{
        "provinceId":16,
        "provinceName":"福建",
        "cityId":1315,
        "cityName":"厦门市",
        "countryId":46764,
        "countryName":"集美区",
        "countrysideId":59176,
        "countrysideName":"杏林街道",
        "address":"福建厦门市集美区杏林街道杏林街道杏锦路*-*号水晶地铁公元*B*",
        "contact":"黄**",
        "phone":"3832358257d66345acbbf0247510a71b0e20c1c2d3813203f1712f405f90d07a24b746", // 取自增强订单列表接口或详情接口中的desen_telephone字段
        "mobile":"3832358257d66345acbbf0247510a71b0e20c1c2d3813203f1712f405f90d07a24b746" // 取自增强订单列表接口或详情接口中的desen_mobile字段
    },
    "weight":0,
    "volume":0,
    "payType":0,
    "shouldPayMoney":0,
    "needGuarantee":false,
    "settlementCode":"1100088xxxxx",// 如果签约的网点是直营型快递，需要传入财务结算编码
    "expressPayMethod":"1",
    "expressType":"1",
    "promiseTimeType":0,
    "guaranteeMoney":0
}]

3、 使用OAID取号

京东于2024年06月新增oaid字段，用于保护收件人隐私（隐掉收件人详细地址，手机号等密文），统一用密文oaid代替，类似淘宝的oaid。可在增强型订单列表中找到对应订单oaid字段的值。下面是使用oaid取号示例。

[
  {
    "branchCode": "571165",
    "fromAddress": {
      "address": "浙江杭州市萧山区新街镇元气沙村328号",
      "cityName": "杭州市",
      "contact": "李先生",
      "countryName": "萧山区",
      "mobile": "18520253322",
      "phone": "18520253322",
      "provinceName": "浙江省"
    },
    "guaranteeMoney": 0,
    "needGuarantee": false,
    "payType": 0,
    "platformOrderNo": "298146510339",
    "promiseTimeType": 0,
    "providerCode": "ZTO",
    "salePlatform": "0010001",
    "shouldPayMoney": 0,
    "templateUrl": "https://template-content.jd.com/template-content?type=standards&id=10000101",
    "toAddress": {
      "address": "山东威海市环翠区怡园街道新的*",// 订单中返回的脱敏收件人详细地址
      "cityName": "威海市",
      "contact": "付**",  // 订单中返回的脱敏收件人姓名
      "countryName": "环翠区",
      "mobile": "177*******6",// 订单中返回的脱敏收件人手机号
      "phone": "177*******6",// 订单中返回的脱敏收件人电话
      "provinceName": "山东",
      "oaid": "YmQ4MDU2ABT5Yz05DTH47QCKVJNOXZu1Yjk1Misehdcv6rs9V5GZHuA2Xfupi4KWHZQPkp/4olMcEal9kcWbg5wU1WJSUHMcsTG37uR/Jldj6p01oi8GIaVnWFwIT6G3Yz5Xp9gdKVH6wZn/s0foJjMsl3dJjBIdf72AVg=="
    },
    "vendorCode": "15138488",
    "vendorName": "薇薇店铺",
    "vendorOrderCode": "1810222361660465154",
    "volume": 0,
    "waybillCount": 1,
    "waybillType": 1,
    "weight": 0
  }
]

顺丰取号的重点参数说明

expressPayMethod: //快递费付款方式(顺丰必填)，1:寄方付 2:收方付 3:第三方付
expressType : // 快件产品类别(顺丰
必填), 快件产品类别，目前顺丰使用，后续可根据承运商自己定义 。1-顺丰标快；2-顺丰特惠

platformOrderNo: 平台订单号,指京东侧的订单号,如255919279479
vendorOrderCode: 商家订单号指商家自己定义的订单号.

2. 请求示例代码(Java)

请求示例代码

   @Test
    public void    wayBillReceive() throws Exception {

        String sellerNick = Config.JDSellerNick ;
        //业务参数
        Map<String, String> data = new HashMap<String, String>();
        data.put("appid",  Config.AppId);
        data.put("seller_nick", sellerNick);
        Long timestamp = System.currentTimeMillis() / 1000;
        data.put("timestamp", timestamp.toString());
         String content ="[" + "  {" + "    \"branchCode\": \"571165\"," + "    \"fromAddress\": {" + "      \"address\": \"浙江杭州市萧山区新街镇元气沙村328号\"," + "      \"cityName\": \"杭州市\"," + "      \"contact\": \"李先生\"," + "      \"countryName\": \"萧山区\"," + "      \"mobile\": \"18520253322\"," + "      \"phone\": \"18520253322\"," + "      \"provinceName\": \"浙江省\"" + "    }," + "    \"guaranteeMoney\": 0," + "    \"needGuarantee\": false," + "    \"payType\": 0," + "    \"platformOrderNo\": \"298146510339\"," + "    \"promiseTimeType\": 0," + "    \"providerCode\": \"ZTO\"," + "    \"salePlatform\": \"0010001\"," + "    \"shouldPayMoney\": 0," + "    \"templateUrl\": \"https://template-content.jd.com/template-content?type=standards&id=10000101\"," + "    \"toAddress\": {" + "      \"address\": \"山东威海市环翠区怡园街道新的*\",// 订单中返回的脱敏收件人详细地址" + "      \"cityName\": \"威海市\"," + "      \"contact\": \"付**\",  // 订单中返回的脱敏收件人姓名" + "      \"countryName\": \"环翠区\"," + "      \"mobile\": \"177*******6\",// 订单中返回的脱敏收件人手机号" + "      \"phone\": \"177*******6\",// 订单中返回的脱敏收件人电话" + "      \"provinceName\": \"山东\"," + "      \"oaid\": \"YmQ4MDU2ABT5Yz05DTH47QCKVJNOXZu1Yjk1Misehdcv6rs9V5GZHuA2Xfupi4KWHZQPkp/4olMcEal9kcWbg5wU1WJSUHMcsTG37uR/Jldj6p01oi8GIaVnWFwIT6G3Yz5Xp9gdKVH6wZn/s0foJjMsl3dJjBIdf72AVg==\"" + "    }," + "    \"vendorCode\": \"15138488\"," + "    \"vendorName\": \"薇薇店铺\"," + "    \"vendorOrderCode\": \"1810222361660465154\"," + "    \"volume\": 0," + "    \"waybillCount\": 1," + "    \"waybillType\": 1," + "    \"weight\": 0" + "  }" + "]";
        data.put("request_data", content);
        data.put("sign", Utils.Sign(data, Config.AppSecret));
        doHttpRequest(Config.JDwayBillReceive, data);
    } 

3. 返回结果如下：

返回结果

{
    "code": 0,
    "message": "ok",
    "data": [
        {
            "data": {
                "platformOrderNo": "255919279479",
                "waybillCodeList": [
                    "SF1637407679724"
                ]
            },
            "statusCode": 0,
            "statusMessage": "success"
        }
    ]
}

业务成功与否参见内层statusCode,0为成功, 同时返回对应的订单号.

4. 说明

4.1 电子面单解绑
如果订单信息，如收件人信息地址改动、修改承运商等，需要调用电子面单解绑接口，然后重新获取单号及大头笔信息
（解绑的运单就作废了，不能再次使用，如果没有解绑，用同样的订单信息，二次获取返回的还是之前的，不会重新生成）
由于顺丰快递一个订单号只允许获取一个运单号，顺丰快递暂不支持解绑
如果解绑顺丰快递时，系统返回“您的订单已绑定一个运单号，顺丰快递暂不支持解除绑定！”

4.2 关于拆单发货
下单接口，平台订单号platformOrderNo相同，商家自有订单号vendorOrderCode不同，也支持获取不同的三方运单号
1.7.1使用拆单功能场景
补发货的情况，同一平台订单，在第一个包裹已经打单发货后，可以使用不同商家自有订单号vendorOrderCode再获取运单号；
多库房发货未知包裹数，需要使用不同的商家自有订单号vendorOrderCode，可以分多次获取运单号；

4.3 关于直营型快递取号
直营型快递会有月结结算编码，相关入参看此文档 https://jos.jd.com/commondoc?listId=335 第2.3.2入参说明

4.4 错误提示：该11位号码为京东虚拟号主号
界电子面单下单接口（jingdong.ldop.alpha.waybill.receive）报错：该11位号码为京东虚拟号主号，请使用完整11-4虚拟号下单。
解答：消费者在APP下单时把虚拟号写到收货人手机号里了，请联系客户修改手机号。