获取电子面单单号和打印信息

主要用于商家ERP/ISV 向字节电子面单系统获取单号和打印信息。
（重要）若取号后再来取号，需传相同订单号及不同的包裹id再次来取号，否则返回老号
调用路径：ISV/商家—>字节
支持批量取号，一次最多100条。

使用本接口获取了快递单号等信息后，再通过接口：查询电子面单（获取面单信息）已经面单信息。

另外：
为方便大家的使用，本接口已经将上面2个步骤合二为一，传入参数，直接返回快递单号和对应的电子面单信息。
合二为一的取号接口：获取电子面单（合二为一）

1.请求参数:

请求URL:

POST https://kf.fw199.com/gateway/dd/logistics/newcreateorder

公共参数

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

业务参数

参数名称	参数类型	是否必须	示例值	参数描述
request_data	json	是	见下面的示例json	获取单号和面单打印数据 ,如果同时对多个订单进行取号，将多个订单信息放到集合order_infos中。

request_data为取号的示例业务报文，json格式如下：

{
    "sender_info":{
        "address":{
            "country_code":"CHN",
            "province_name":"上海市",
            "city_name":"上海市",
            "district_name":"青浦区",
            "detail_address":"测试"
        },
        "contact":{
            "name":"hanson",
            "mobile":"18817834074"
        }
    },
    "logistics_code":"zhongtong",
    "order_infos":[
        {
            "order_id":"49488636457864312061",
            "pack_id":"pkg_01",
            "receiver_info":{
                "address":{
                    "country_code":"CHN",
                    "province_name":"浙江省",
                    "city_name":"杭州市",
                    "district_name":"西湖区",
                    "detail_address":"#ZbZE6fdvKu0n/gB488d4Uxj7bzQi#n3zBNQgaGXiMjQb7CIwUDrQ/oEQGP43PmvV9Oi4lTooQagOruEjHzoy8JiUfZ/+3kOQABhWWXbhtTCKXDaE5GrNfbVhmef3N2d1u4eIDRZ6cT4fAsxUY4eCRTD+3pg==*CgwIARCtHBiYJSABKAESPgo8azkO9VDljulg7gl8Z8ykmOOfh93YeeMY+p+VbuytBkgfmS61mTnWtH4omldn44DJ4b7CZPzdDybE/QFBGgA=#1##"
                },
                "contact":{
                    "name":"#JsKP#mjMUmDSsFnoIZQyxnI8dKvJm7af8F+6YU+ZQRYZRGpukzSczT5arppGdExz9pleid3zCHGr8FvBmFsMmU5mmZ03F8k/dCNEy*CgwIARCtHBiYJSABKAESPgo8EGql2MQlYZNFj1iHVlSK41VeEYk0sH3UrzR5/8nYgPlbhkrbI2fbWQmlYrkuSJig7K3SHQi1jI6oXkp5GgA=#1##",
                    "mobile":"$dzFmfVaRHLlEEdPMqNWcR5WZ01oatEm4hTtC3iO9+sM=$0uwlr1TmDiJNYFPgdS1vCTOdq2ZxXk1ed8aSS8AZLpa8itQk/L9noLXPPnyWt6VOF3ZyyC+N00OGk09TzF+4/Mtn4VeJ0OGAPqZtGTlJGJxx*CgwIARCtHBiYJSABKAESPgo88ghgupGfSv8mUFdaXWzO3J54gbTj1192xyPJJUHcxjR0SqFUEdfoeUVsLKK6EaekOkvU5OTFCWgREZehGgA=$1$$"
                }
            },
            "items":[
                {
                    "item_name":"【测试商品勿拍】白色水墨印花衬衣",
                    "item_specs":"颜色:默认 尺码:120cm",
                    "item_count":1
                }
            ]
        },
        {
            "order_id":"4948795729456854758",
            "receiver_info":{
                "address":{
                    "country_code":"CHN",
                    "province_name":"浙江省",
                    "city_name":"杭州市",
                    "district_name":"西湖区",
                    "detail_address":"#88d4Uxj7bzQiCZ/tB348#JYQbCE0Z3qS4enifncvRfvy/2//ByIgja0ez2ziH5ejCsBpPzEZ1sSuUDukoVKuQHCIok56Ew2jW/BDm4cri1uAWizYOx5y2JIB2ulq0mxMpj5OtkzMqtg==*CgwIARCtHBiYJSABKAESPgo8ak9uAm8xewS+3cxuj53pXMk1QHFjZPL4lRR6ReHcY/n46MfiA2HAos7aQ2k7eAoqlY9IDo9SgUDxcugRGgA=#1##"
                },
                "contact":{
                    "name":"#JsKP#MU+XJbCwo6OvX9i6/9FGQfXBEikV2PhUf/Y+SvMTXJxVvDfGsu6sZkB/66vPHkQ7eot/UFyVXEiJnhq+rES6wlm5fcvybYJY*CgwIARCtHBiYJSABKAESPgo8iXhpCxN3TRpdw1c354bgKOqDbL9yt0J9qBUSIY/bLcW41gWAURRt6Nxp11BTrA4key6atmBb/BMdActIGgA=#1##",
                    "mobile":"$dzFmfVaRHLlEEdPMqNWcR5WZ01oatEm4hTtC3iO9+sM=$Ws0Fjzxv1wXfWsPGHS1XMv6riNju8b3AJtk/fiTAHaOiVUf9h+YSlBuVjF18SAAIA5ymX6H/V6q/HPc0vIUvuTViP4TM40i3RaWOMd7se5At*CgwIARCtHBiYJSABKAESPgo8f8TVWjyoVQNlT7MEj7tPiYwTpuHZWzKSuMWMsi0UV3oIMsp2U3rUASks98PnPsr0i3IwvzrOTMPYbiBnGgA=$1$$"
                }
            },
            "items":[
                {
                    "item_name":"【【测试商品勿拍】dy测试上衣-各种编码3",
                    "item_count":1
                }
            ]
        }
    ],
    "user_id":-1,
    "order_channel":"1"
}

上述请求参数字段的以及更多字段的业务含义说明见文档

2. 请求示例代码(Java)

  @Test
    public void  DDLogisticsWaybillGet() throws Exception {

         String reqData = "{\"sender_info\": {" +
            "        \"address\": {" +
            "            \"country_code\": \"CHN\"," +
            "            \"province_name\": \"上海市\"," +
            "            \"city_name\": \"上海市\"," +
            "            \"district_name\": \"青浦区\"," +
            "            \"detail_address\": \"测试\"" +
            "        }," +
            "        \"contact\": {" +
            "            \"name\": \"hanson\"," +
            "            \"mobile\": \"18817834074\"" +
            "        }" +
            "    }," +
            "    \"logistics_code\": \"zhongtong\"," +
            "    \"order_infos\": [" +
            "        {" +
            "            \"order_id\": \"4948863645786431206\"," +
            "            \"pack_id\": \"pkg_01\"," +
            "            \"receiver_info\": {" +
            "                \"address\": {" +
            "                    \"country_code\": \"CHN\"," +
            "                    \"province_name\": \"浙江省\"," +
            "                    \"city_name\": \"杭州市\"," +
            "                    \"district_name\": \"西湖区\"," +
            "                    \"detail_address\": \"#ZbZE6fdvKu0n/gB488d4Uxj7bzQi#n3zBNQgaGXiMjQb7CIwUDrQ/oEQGP43PmvV9Oi4lTooQagOruEjHzoy8JiUfZ/+3kOQABhWWXbhtTCKXDaE5GrNfbVhmef3N2d1u4eIDRZ6cT4fAsxUY4eCRTD+3pg==*CgwIARCtHBiYJSABKAESPgo8azkO9VDljulg7gl8Z8ykmOOfh93YeeMY+p+VbuytBkgfmS61mTnWtH4omldn44DJ4b7CZPzdDybE/QFBGgA=#1##\"" +
            "                }," +
            "                \"contact\": {" +
            "                    \"name\": \"#JsKP#mjMUmDSsFnoIZQyxnI8dKvJm7af8F+6YU+ZQRYZRGpukzSczT5arppGdExz9pleid3zCHGr8FvBmFsMmU5mmZ03F8k/dCNEy*CgwIARCtHBiYJSABKAESPgo8EGql2MQlYZNFj1iHVlSK41VeEYk0sH3UrzR5/8nYgPlbhkrbI2fbWQmlYrkuSJig7K3SHQi1jI6oXkp5GgA=#1##\"," +
            "                    \"mobile\": \"$dzFmfVaRHLlEEdPMqNWcR5WZ01oatEm4hTtC3iO9+sM=$0uwlr1TmDiJNYFPgdS1vCTOdq2ZxXk1ed8aSS8AZLpa8itQk/L9noLXPPnyWt6VOF3ZyyC+N00OGk09TzF+4/Mtn4VeJ0OGAPqZtGTlJGJxx*CgwIARCtHBiYJSABKAESPgo88ghgupGfSv8mUFdaXWzO3J54gbTj1192xyPJJUHcxjR0SqFUEdfoeUVsLKK6EaekOkvU5OTFCWgREZehGgA=$1$$\"" +
            "                }" +
            "            }," +
            "            \"items\": [" +
            "                {" +
            "                    \"item_name\": \"【测试商品勿拍】白色水墨印花衬衣\"," +
            "                    \"item_specs\": \"颜色:默认 尺码:120cm\"," +
            "                    \"item_count\": 1" +
            "                } " +
            "            ]" +
            "        }" +
            "    ]," +
            "    \"user_id\": -1," +
            "    \"order_channel\": \"1\"" +
            "}";

        Map<String, Object> data = new HashMap<String, Object>();
        data.put("appid", Config.AppId);
        Long timestamp = System.currentTimeMillis() / 1000;
        data.put("timestamp", timestamp.toString());
        data.put("seller_nick", Config.DDSellerNick);
        data.put("request_data", reqData);
        data.put("sign", Sign(data, Config.AppSecret));
        // 调用服务API
        String resp = doHttpRequest(Config.DDLogisticsWaybillGetUrl, data);
        System.out.println(resp);

    }

说明：取号也支持明文取号，将收件人详细地址detail_address、收件人姓名name、收件人手机mobile传入明文即可。

3. 返回结果如下：

{
    "code":0,
    "message":"ok",
    "data":{
        "ebill_infos":[
            {
                "order_id":"4948795729456854758",
                "pack_id":"",
                "track_no":"75531717195834",
                "sort_code":"320- 13 128",
                "package_center_code":"",
                "package_center_name":"杭州",
                "short_address_code":"",
                "short_address_name":"",
                "extra_resp":"",
                "sub_waybill_codes":"",
                "order_channel":"1",
                "shipping_code":""
            }
        ],
        "err_infos":[
            {
                "order_id":"49488636457864312061",
                "pack_id":"pkg_01",
                "err_code":"4006",
                "err_msg":"49488636457864312061:订单号非法",
                "order_channel":"1"
            }
        ]
    }
}

返回参数说明

参数名称	参数类型	是否必须	示例值
order_id	String	202011809	订单号
pack_id	String	1	包裹id
track_no	String	202011809	运单号
print_data	String		加密的面单数据
err_code	int		错误码,0表示成功，非0失败
err_msg	String		取号失败时，返回的信息
sort_code	String	400-W00 000	分拣码（三段码）
package_center_code	String	1	集包地代码
package_center_name	String	1	集包名称
short_address_code	String	1	大头笔编码
short_address_name	String	1	大头笔名称
extra_resp	String	1	额外打印信息（众邮、京东、丰网使用），具体请参考抖音电商电子面单对接文档附录4
sub_waybill_codes	String	13,434,556	子母件列表英文逗号分隔
order_channel	String	c	2；详情请看文档映射表
shipping_code	String	34343	快递商侧系统生成的寄件码

说明： code为0表示成功，非0为失败，message会包含失败原因。此接口为批量取号接口，多个订单同时取号时，取号失败的订单也会返回，是否成功以err_code为准，err_msg会包含失败的原因。

4. 多店铺共享面单库存&非抖店面单取号方案

当取号接口返回提示“查询订单失败”时，一般是渠道和订单号与店铺不一致造成的，一般有如下2种情况：

4.1 主店铺A帮其他副店铺B（抖音平台的店铺）取号时，即A出号给B使用。

这种情况，取号参数中的user_id传B店铺的店铺ID。若无法获取到B店铺的店铺ID，传值 -1 可绕过order_id与user_id的一致性校验。

4.2 主店铺A帮其他副店铺B（非抖音平台的店铺）取号时，即A出号给B使用。

这情况下，因为传入的订单号order_id是其他平台渠道的订单号，所以还要传入order_channel渠道代码（不传或传1是代表抖音），所以order_channel要传其他平台的代码。其他平台的代码表如下：

渠道名称	渠道编码（接口交互使用） order_channel
抖音	1
快手	2
淘宝	3
天猫	4
京东	5
拍拍	6
易讯	7
当当	8
EBAY	9
亚马逊	10
QQ	11
苏宁	12
国美	13
唯品会	14
聚美	15
乐蜂	16
蘑菇街	17
聚尚	18
拍鞋	19
银泰	20
1号店	21
凡客	22
邮乐	23
优购	24
1688	25
有赞	26
拼多多	27
折800	28
楚楚街	29
卷皮	30
贝贝	31
微店	32
千米	33
美丽说	34
返利	35
萌店	36
网易严选	37
微盟	38
微商	39
小米	40
考拉	41
蜜芽	42
云集	43
贝店	44
闲鱼	45
玩物得志	46
小红书	47
华为	48
洋码头	49
我买	50
酒仙网	51
本来生活	52
得物	53
小荷健康商城	55
微信视频号	56
字节供应链	101
字节抖音超市	102

4.3 接口报错“详细地址长度不能超过200字符，请检查重试”

详细地址的密文传入有问题，无法识别，会被当成明文校验，需要传入正确的密文。

文档更新时间: 2024-04-10 15:34 作者：admin