一、总则

灰度期（2024.11.30-2025.03.31日），新版电子面单和老版电子面单会同时并存；2025.03.15日开始已禁止旧版电子面单订购，2025.04.01日开始灰度禁止旧版电子面单取号，如需申请加白请关注平台公告。

所有的电子面单接口需要增加一个参数billVersion=2切换到新版本电子面单，默认billVersion=1代表老版电子面单。

新旧电子面单模板的语法完全不同，需要根据最新的模板语言重新绘制自定义模板，新版不再兼容菜鸟电子面单模板。

新版电子面单需要下载并安装新版电子面单打印组件，下载地址：windows版、mac版。

打印websocket协议和之前的打印协议保持一致，但是只支持print、getPrinters、getAgentInfo这3个指令。

同一个商家在快递公司开通的新版电子面单账号和老版本的账号是不相同的，需要商家在小红书新版电子面单页面重新发起网点订购，并且需要注意面单充值的时候不要混淆账号将面单充值到了旧账号。

因为新版、旧版的数据不相通，需要ISV在系统上体现小红书电子面单新版和旧版的差异，并引导商家逐步切换至新版。

二、接口改造

2.1 接口差异

新版需要调用快递公司取号并计算路由，平均RT会比旧版电子面单增多。

新版取消回收由快递公司控制，和快递公司的通用回收规则保持一致，如果对回收有疑问可以咨询物流服务商。

新版申通、京东、顺丰仍然调用批量取号接口取号，但是不支持在一次接口调用时获取多个面单号。

新版批量取号接口支持部分成功部分失败。

2.2 快递公司和旧版的差异

中通：查询订购接口面单使用情况只返回面单余额；保价范围(1,30000]。

京东：不支持一次取多个运单号，但是如果是同一个运单的子母单可以批量获取；默认上门预约。不支持温层的产品类型取号时不再允许传温层字段warmLayer，否则会报错：产品属性错误,不支持warmLayer。

德邦快递：支持子母单；支持追加子单；新增了产品类型（不传默认为标准快递）。

申通：不支持一次取多个运单号；新增申咚咚增值服务；不再支持生鲜件增值服务；保价增值服务需要订购审核通过后才能生效，保价单位支持整数元，当传小数的时候会向上取整；查询订购接口面单使用情况只返回面单余额。

顺丰：不支持普通面单一次取多个运单号，但是如果是同一个运单的子母单可以批量获取；增加了支付方式payMethod；支持上门预约；支持更新收发件人信息。顺丰的abFlag是根据托寄物字段商品名称item.name进行识别的，平台提供的主模板会根据顺丰的返回的标识绘制好图标，不需要ISV再自行绘制。

极兔：查询订购接口面单使用情况不返回取消数。

邮政：增值服务传参没有做强校验，如果服务编码不存在直接忽略，仍然会取号成功。

菜鸟速递：不支持面单更新。

圆通：新增保价增值服务；新增了产品类型（不传默认为标准快递）。参数枚举请查看文档【电子面单对接说明（新）】

2.3 批量取号接口

新版批量取号会存在部分成功、部分失败的情况。

取号全部失败，外层的success=false。

取号部分成功，只要有一单成功则外层的success=true，wayBillList里面每个订单都会有结果，success=true或者waybillCode不为空代表这个订单取号成功，success=false代表订单取号失败，失败原因看errorMsg。

旧版取号接口要么全部取号成功，要么全部失败。

取号全部失败，外层的success=false，不返回wayBillList。

取号全部成功，外层的success=true，wayBillList每个订单的success=true。

模板ID字段templateId，新版和旧版的值完全不同，如果混用会取号失败，提示【模板id和当前面单版本不匹配】

2.4 面单模板接口

当type=""或者不传值时，会返回小红书预设的标准模板

当type=ark时，会返回商家在小红书千帆系统上配置的模板 + 商家在小红书云打印系统ERP应用下创建的商家自定义区列表

如果ISV希望同时有标准模板和商家自定义模板，则需要调用两次接口自己组合，一次type传空字符串，一次type传ark。

商家在云打印系统创建的商家自定义模板的自定义类型templateCustomerType=10，如果ISV仅仅希望获取商家在小红书云打印系统上创建的模板传参是type=ark和templateCustomerType=10；但是当ISV还希望获取到商家在小红书千帆系统上编辑的模板，建议仅传type=ark即可。

三、面单模板语法

语法文档可参考小红书云打印系统物料使用说明书。新版电子面单是json格式，通过小红书云打印系统在线编辑模板会更加方便。

通过#data.xxx获取data里面的数据，文本组件的[内容]里面可以写javascript表达式。

常见组件内容表达式：

自定义区域展示订单+商品+留言： [...#data.order,...#data.item,...#data.buyerMemo,...#data.sellerMemo]

基于快递公司展示不同的文本：({ "ems": "特快", "youzhengbiaokuai": "电商\n标快" })[#data.cpCode] || "标准\n快递"

匿名函数：#data.nullFiled || (() => { return "123123"})();

匿名函数：

(() => {
    if (#data.cpCode === 'ems') {
        return "EMS";
    }
    return #data.cpCode;
})()

增值服务处理示例：

// 示例
((cpCode, services) => {
    // 代收货款
    var SVC_COD_VALUE = (services["SVC-COD"] || "").toString();
    return SVC_COD_VALUE;
})(#data.cpCode, (#data.shippingOption || {}).services || {});

四、打印协议

只支持print、getPrinters、getAgentInfo这3个指令，详见电子面单打印组件协议(新)

五、常见问题

Q：需要在什么时候完成电子面单改造？

A：建议在11.30前完成改造，这样可以确保商家及时使用新版电子面单

Q：是否可以系统自动迁移将订购关系迁移到新版电子面单？

A：无法实现，需要商家手动在新版电子面单重新进行订购。新版电子面单页面提供了【一键切换】功能可以进行一键订购，但是对于顺丰和京东需要商家先对每个月结卡号手动订购一次以后才可以通过【一键切换】订购其他地址，对于其他快递平台会用旧版的订购信息向快递公司发起订购，然后需要等待服务商网点进行审核。

Q：平台是否可以提供测试店铺给到ISV联调？

A：

建议ISV优先使用自己的正式店铺开通电子面单进行测试，可以在小红书上搜索如何开店快速开店，电子面单业务不需要缴纳保证金就可以使用。

平台不能直接给到测试店铺账号密码，但是平台的测试店铺可以对ISV的应用授权。需要开发者在答疑群联系我们提供应用ID，我们对应用手动授权后得到一个授权token给到开发者，开发者需在10分钟以内换取accessToken。

注意：平台测试店铺获取的面单仅用来测试取号打单，不能用来走实单，一经发现违规走单，小红书将对应用做下架处理。

平台的测试店铺京东取号测试寄件人手机号和地址必须为以下列出的手机号和地址

北京/大兴区/清源街道北京市大兴区亦庄经济开发区给外单的测试地址哈

北京/大兴区/北京经济技术开发区北京市大兴区亦庄经济开发区给快运uat集配站测试面单打印AOI提供的测试地址1

限定手机号为：12993300000、12993300001、12993300010、12993300011

Q：为什么商家店铺无法看到新版电子面单？

A：目前所有商家都已经开放了新版入口，在小红书电子面单页面的顶部有入口可以进入新版。

Q：配置了新版白名单以后是否影响旧版的使用？

A：

新版和旧版是可以同时使用的，打印组件可以同时打开，商家开通新版后不会对旧版产生影响，但是要注意的旧版取号的面单要用旧版打印组件打印，新版取号的面单要用新版打印组件打印。

开通新版不需要重新申请店铺，新版和旧版在同一个店铺中可以同时使用。

店铺授权只是店铺对应用的授权，和电子面单没有关系，授权后ISV可以通过调用电子面单接口对同一个店铺进行新版取号和旧版取号。

Q：店铺面单余额是否支持迁移？

A：需要客户与合作网点沟通，先将旧版账户a的余额清退，然后重新充值到新版账户b。商家开通新版电子面单以后，仍然可以使用旧版电子面单，待旧版的余额用完以后再切换至新版面单，注意在面单充值的时候提醒网点人员不要充错账号。

Q：新版自定义模板怎么生成？

A：新版自定义模板的尺寸和使用规则和旧版相同，但是不能再使用菜鸟模板，可以用开放平台账号或者千帆商家账号登录小红书云打印系统进行编辑。如果希望在自己的ERP系统上绘制模板，请参考文档：小红书云打印系统物料使用说明书。旧版打印模板的内容是xm格式，新版打印模板的内容是json格式，新旧版的模板语法完全不同，不要混淆。

Q：新版主要涉及到哪些改动？

A：对于商家：需要在新版电子面单页面重新订购，编辑新的模板，往新的电子面单账号进行充值，然后安装新的打印组件进行打单。

对于ISV：

所有对接的电子面单接口仍然复用之前的接口，增加了billVersion字段，billVersion=1代表旧版接口，billVersion=2代表新版接口，通过billVersion=1得到的都是旧版数据，通过billVersion=2得到的都是新版数据，旧版数据和新版数据完全隔离。

打印组件协议和旧版相同，但是只支持核心指令。

打印模板语法完全不兼容，旧版是xml格式，新版是json格式。

Q：新版电子面单对比旧版电子面单的优势在哪里？

A：新版电子面单是由小红书直接和快递公司对接，支持更多定制化需求；

新版云打印系统和小红书千帆系统进行了打通，商家可以自己对自定义区域进行灵活变换；

新版打印客户端是小红书自研，故障排查会更加便捷。

Q：如何区分新版和旧版电子面单？

A：新版电子面单账号长度是18位，以13开头；旧版电子面单账号的长度的15位，以10开头；更详细的可参考电子面单常见问题。

Q：如何联系平台咨询问题？

A：可以扫描下面的二维码进入电子面单ISV答疑群，答疑时间：工作日下午2:00-3:00。

新版小红书电子面单ISV对接改造

一、总则#

二、接口改造#

2.1 接口差异#

2.2 快递公司和旧版的差异#

2.3 批量取号接口#

2.4 面单模板接口#

三、面单模板语法#

四、打印协议#

五、常见问题#