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

主要用于商家ERP/ISV 向字节电子面单系统获取单号和打印信息。
（重要）关于出新号或老号的问题： 如果 订单号+ 包裹id 相同，则返回老号， 如果包裹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字符，请检查重试”

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

4.4 查询电子面单信息返回失败，提示’该运单不存在或已删除’，如何解决？

该报错可能有两种情况引起：1、运单号被取消了；2、运单号取号太久，没有打印，被回收了。 3、通过A店铺获取单号，再用单号通过B店铺获面单
平台建议开发者遇到该问题，可重新取号再打印。

4.5 明文和密文取号与渠道编码的关系

看一下这个规则 https://op.jinritemai.com/docs/question-docs/1263/6731

文档更新时间: 2024-09-30 10:43   作者：admin