电子面单取号

用于ISV获取快手电子面单场景（批量接口，最多50）

1.请求参数:

请求URL:

POST https://kf.fw199.com/gateway/ks/express/ebill/get

参数名称 参数类型 是否必须 示例值 参数描述
appid String 是 合作伙伴AppId
timestamp String 是 1657525936 当前Unix时间戳，秒
seller_nick String 是 38173182 快手的店铺账号，对应蜂巢授权返回seller_nick字段
sign String 是

业务参数

参数名称 参数类型 是否必须 示例值 参数描述
request_data json 是 获取号业务报文，支持批旺取号，一次不超过对50个订单进行取号

取号业务报文参数request_data示例json

[
    {
        "expressCompanyCode": "SF",
        "extData": "{\"isvClientCode\":\"0220602221\"}",
        "itemList": [
            {
                "itemQuantity": 1,
                "itemTitle": "专用的回形针"
            }
        ],
        "merchantCode": "f198f0846993046e14bf572443812bdb",
        "merchantName": "刻骨铭心的爱情",
        "orderChannel": "KUAI_SHOU",
        "packageCode": "pk2023022002-1",
        "payMethod": 1,
        "receiverAddress": {
            "cityName": "杭州市",
            "detailAddress": "",
            "districtName": "余杭区",
            "provinceName": "浙江省"
        },
        "receiverContract": {
            "mobile": "18868751233",
            "name": "张三"
        },
        "requestId": "2023022002-1",
        "senderAddress": {
            "cityName": "市辖区",
            "detailAddress": "商城路123号",
            "districtName": "浦东新区",
            "provinceName": "上海市"
        },
        "senderContract": {
            "mobile": "18817832222",
            "name": "张三"
        },
        "settleAccount": "0220602221",
        "totalPackageQuantity": 1,
        "tradeOrderCode": "334553"
    },
    {
        "expressCompanyCode": "SF",
        "extData": "{\"isvClientCode\":\"0310626997\"}",
        "itemList": [
            {
                "itemQuantity": 1,
                "itemTitle": "专用的回形针"
            }
        ],
        "merchantCode": "f198f0846993046e14bf572443812bdb",
        "merchantName": "刻骨铭心的爱情",
        "orderChannel": "KUAI_SHOU",
        "packageCode": "pk2023022002-2",
        "payMethod": 1,
        "receiverAddress": {
            "cityName": "杭州市",
            "detailAddress": "~AjbKvY9u2S0CIAjAg1ZIexIqfPKO6hgR zASMBO5HeMwJW/w3na6hcpj4yrNWOgHkJbspR/2TLqNMC2E7bpLtw5Lx0rC6/Urzg6DjBoSPMmhB7hLoPBjQBZQFkF/AV6eIiDtbUTTWJMAKwxokr6+NpAy9GwleML6Rco4vN7gZSurpCgFMAE=~1~~",
            "districtName": "余杭区",
            "provinceName": "浙江省"
        },
        "receiverContract": {
            "mobile": "$hgj0WBf4KDketN0trlrGWCivd4lGi o5AkXt+jRzJ8okryjXGMhGkBVcwvlDZhk2RxJRGAFSgFMAE=$1$$",
            "name": "#YM+/f/VLf/VL#Ci1tZXJjaGFudC5vc JyNHQxuygFMAE=#1##"
        },
        "requestId": "2023022002-2",
        "senderAddress": {
            "cityName": "市辖区",
            "detailAddress": "商城路123号",
            "districtName": "浦东新区",
            "provinceName": "上海市"
        },
        "senderContract": {
            "mobile": "18817832222",
            "name": "张三"
        },
        "settleAccount": "0220602221",
        "totalPackageQuantity": 1,
        "tradeOrderCode": "2307500074108220"
    }
]

关于明文取号

本取号接口也支持明文取号，只要在下面3个收件人相关字段传入明文

  1. receiverContract.mobile 传入明文格式的收件人手机号码，比如：13877778888
  2. receiverContract.name 传入明文格式的收件人姓名，比如：张三
  3. receiverAddress.detailAddress 传入明文格式的详细地址，比如：东方路200号EFC-T6-大厦

请求参数各字段说明见文档： https://open.kwaixiaodian.com/docs/api?apiName=open.express.ebill.get&version=1

2. 请求示例代码(Java)

  @Test  
public void ExpressEbillGet() throws Exception {  

    String sellerNick = Config.KSSellerNick ;  
    //业务参  
    Map<String, String> data = new HashMap();  
    data.put("appid",  Config.AppId);  
    data.put("seller_nick", sellerNick);  
    Long timestamp = System.currentTimeMillis();  
    data.put("timestamp", timestamp.toString());  
   String reqData = "[\n" +  
            "    {\n" +  
            "        \"expressCompanyCode\": \"SF\",\n" +  
            "        \"extData\": \"{\\\"isvClientCode\\\":\\\"0210606997\\\"}\",\n" +  
            "        \"itemList\": [\n" +  
            "            {\n" +  
            "                \"itemQuantity\": 1,\n" +  
            "                \"itemTitle\": \"专用的回形针\"\n" +  
            "            }\n" +  
            "        ],\n" +  
            "        \"merchantCode\": \"f198f0846993046e14bf572443812bdb\",\n" +  
            "        \"merchantName\": \"刻骨铭心的爱情\",\n" +  
            "        \"orderChannel\": \"KUAI_SHOU\",\n" +  
            "        \"packageCode\": \"pk2023022002-1\",\n" +  
            "        \"payMethod\": 1,\n" +  
            "        \"receiverAddress\": {\n" +  
            "            \"cityName\": \"杭州市\",\n" +  
            "            \"detailAddress\": \"\",\n" +  
            "            \"districtName\": \"余杭区\",\n" +  
            "            \"provinceName\": \"浙江省\"\n" +  
            "        },\n" +  
            "        \"receiverContract\": {\n" +  
            "            \"mobile\": \"18868751267\",\n" +  
            "            \"name\": \"张三\"\n" +  
            "        },\n" +  
            "        \"requestId\": \"2023022002-1\",\n" +  
            "        \"senderAddress\": {\n" +  
            "            \"cityName\": \"市辖区\",\n" +  
            "            \"detailAddress\": \"商城路738号\",\n" +  
            "            \"districtName\": \"浦东新区\",\n" +  
            "            \"provinceName\": \"上海市\"\n" +  
            "        },\n" +  
            "        \"senderContract\": {\n" +  
            "            \"mobile\": \"18817834074\",\n" +  
            "            \"name\": \"hanson\"\n" +  
            "        },\n" +  
            "        \"settleAccount\": \"0210606997\",\n" +  
            "        \"totalPackageQuantity\": 1,\n" +  
            "        \"tradeOrderCode\": \"334553\"\n" +  
            "    },\n" +  
            "    {\n" +  
            "        \"expressCompanyCode\": \"SF\",\n" +  
            "        \"extData\": \"{\\\"isvClientCode\\\":\\\"0210606997\\\"}\",\n" +  
            "        \"itemList\": [\n" +  
            "            {\n" +  
            "                \"itemQuantity\": 1,\n" +  
            "                \"itemTitle\": \"专用的回形针\"\n" +  
            "            }\n" +  
            "        ],\n" +  
            "        \"merchantCode\": \"f198f0846993046e14bf572443812bdb\",\n" +  
            "        \"merchantName\": \"刻骨铭心的爱情\",\n" +  
            "        \"orderChannel\": \"KUAI_SHOU\",\n" +  
            "        \"packageCode\": \"pk2023022002-2\",\n" +  
            "        \"payMethod\": 1,\n" +  
            "        \"receiverAddress\": {\n" +  
            "            \"cityName\": \"杭州市\",\n" +  
            "            \"detailAddress\": \"~AjbKvY9u2S0CIAjAg1ZIexIqfPKO6hgRofbOMD04wm89vY9uhyivF0zeW4oXfPKOTFdIbxjQB6AzvMOy~Ci1tZXJjaGFudC5vcGVuLnNlY3JldC5rZXkua3M2ODk2MTM2OTY3MzMyMTA0NzASUMozwjqjgUFiZ9zj7hQBOT9VIAlS9IPgS67NA33OItK1WU3HEP/2sxfLSIoWr/exrYv7rtlXRnf4Ni5zNiWOe7K21NwbENDVYePe3KDYL3MuGhJzMgJtP5PjYvGieLI5U5hDKdEiIGQbAshq173PVT0zfaWpkhjxWLv9iZEoRyTFON+fJao/KAUwAQ==\\u0026Ci1tZXJjaGFudC5vcGVuLnNlY3JldC5rZXkua3M2ODk2MTM2OTY3MzMyMTA0NzASMBO5HeMwJW/w3na6hcpj4yrNWOgHkJbspR/2TLqNMC2E7bpLtw5Lx0rC6/Urzg6DjBoSPMmhB7hLoPBjQBZQFkF/AV6eIiDtbUTTWJMAKwxokr6+NpAy9GwleML6Rco4vN7gZSurpCgFMAE=~1~~\",\n" +  
            "            \"districtName\": \"余杭区\",\n" +  
            "            \"provinceName\": \"浙江省\"\n" +  
            "        },\n" +  
            "        \"receiverContract\": {\n" +  
            "            \"mobile\": \"$hgj0WBf4KDketN0trlrGWCivd4lGiRW76Ndomhp9c4E=$Ci1tZXJjaGFudC5vcGVuLnNlY3JldC5rZXkua3M2ODk2MTM2OTY3MzMyMTA0NzASICwvm6s75FDHKgVIerueNzDCA0hH9epE9EHGGKZE3dKnGhJWRKj7d9Wev4sJi4wZlE5MxFIiIP7pD6XdbppHN/Q+CfnSIqSWoXTfNXNWxfu/Iox9ON+tKAUwAQ==\\u0026Ci1tZXJjaGFudC5vcGVuLnNlY3JldC5rZXkua3M2ODk2MTM2OTY3MzMyMTA0NzASMLCaljE45X6stGqAdyPjzrMytdj0skLt0EWSoBBEIjG1kYAKy8RzVWFnkkKETr9sbhoSBnwvuCIdjVwx6EtttwjivnCcIiDlo5AkXt+jRzJ8okryjXGMhGkBVcwvlDZhk2RxJRGAFSgFMAE=$1$$\",\n" +  
            "            \"name\": \"#YM+/f/VLf/VL#Ci1tZXJjaGFudC5vcGVuLnNlY3JldC5rZXkua3M2ODk2MTM2OTY3MzMyMTA0NzASIKhFchMiKh5/WfUiIWQmipT4voSwfdKyd9NB8BrLOjHVGhLXplPWFR7sNZP9RgRMGML7FX8iIFkiN0E3YQa4ueKLT/6fA7vXi4UWYzeooc/QRlgE5UqsKAUwAQ==\\u0026Ci1tZXJjaGFudC5vcGVuLnNlY3JldC5rZXkua3M2ODk2MTM2OTY3MzMyMTA0NzASMMxey7iIPpxLqmmTmJ+OBsAeH8Kc/G6vzcQrOrhqqdJCC18HxlQ/qioGVJjyrdCFLBoSmLtjyQ6jY6nVENp0OjZZ6HqTIiDUK68C7bh1IfXGaYrVgfii0lFNJfggJTluf1JyNHQxuygFMAE=#1##\"\n" +  
            "        },\n" +  
            "        \"requestId\": \"2023022002-2\",\n" +  
            "        \"senderAddress\": {\n" +  
            "            \"cityName\": \"市辖区\",\n" +  
            "            \"detailAddress\": \"商城路738号\",\n" +  
            "            \"districtName\": \"浦东新区\",\n" +  
            "            \"provinceName\": \"上海市\"\n" +  
            "        },\n" +  
            "        \"senderContract\": {\n" +  
            "            \"mobile\": \"18817834074\",\n" +  
            "            \"name\": \"hanson\"\n" +  
            "        },\n" +  
            "        \"settleAccount\": \"0210606997\",\n" +  
            "        \"totalPackageQuantity\": 1,\n" +  
            "        \"tradeOrderCode\": \"2307500074108220\"\n" +  
            "    }\n" +  
            "]";  
    data.put("request_data",reqData);  
    // 参数签名  
    data.put("sign", Utils.Sign(data, Config.AppSecret));  
    String result = doHttpRequest(Config.KS_OPEN_EXPRESS_EBILL_GET, data);  
    System.out.println("result:"+result);  
}

3. 返回结果

返回结果如下 

 {
    "code": 0, // 
    "message": "ok",
    "data": [
        {
            "waybillPackageCode": "",
            "parentWaybillCode": "",
            "signature": "317e3eda151a558f44bfec122b92699a",
            "waybillCode": "SF1604143659111",
            "printData": "5368D5E03900048DD985F0811E432DF916302Bxxxxxxxxxxxxxxxx",
            "version": "1",
            "key": "W46fz1vRb25/RFf400xtxB/a+WrEbk/a3mNjhUSJufnZT01xtwrwlVxxxxxxxxxx=",
            "requestId": "2023022002-2",
            "code": 0,
            "message": ""
        },
        {
            "waybillPackageCode": "",
            "parentWaybillCode": "",
            "signature": "",
            "waybillCode": "",
            "printData": "",
            "version": "",
            "key": "",
            "requestId": "2023022002-1",
            "code": 2,
            "message": "收件地址信息为空或信息不规范 收件地址信息为空或信息不规范"
        }
    ]
}

code为0时，表示系统层面成功。 注意内层的code为每个订单取号的结果，code为0时取号成功，失败的话，见message字段，会有提示说明。

取到电子面单和快递单号以后，再将数据按快手官方要求进行组装，丢给官方的打印组件。
快手官方电子面单打印组件对接文档：https://docs.qingque.cn/d/home/eZQDbkSPtH2wPCMgRWDpASUJk?identityId=1oEFwmDizx5#section=h.kujk5mprt6pw

主要业务参数说明

参数名 类型 必须 示例值
waybillCode String 319787688997698 电子面单号
printData String iooho97900m,d@kdj 打印数据（JSON格式）
parentWaybillCode String 319787688997697 母电子面单号
version String 1 版本号
signature String fdsfsd78867fds 签名
key String hlkklfod879 key
waybillPackageCode String JDV006309839589-1-1- 运单包裹号（仅京东使用）

四、常见问题

4.1 收件人姓名超过128个字符 收件人姓名超过128个字符

A： 检查传入的orderChannel是否KUAI_SHOU，只有快手自己平台的密文才可以解。否则会报这些问题。
不同的订单渠道标识：(https://docs.qingque.cn/s/home/eZQCPgx29ls1rz4l7efnPfMiH?identityId=EmukFTnlEF)

文档更新时间: 2024-09-05 17:02   作者：admin