电子面单常见问题（新）

温馨提示： 小红书新版电子面单已上线，11.30开始按照比例灰度商家。新对接的自研商家建议直接接入新版电子面单，在小红书千帆系统电子面单页面的顶部可以点击新版电子面单进入新版。如需查阅旧版电子面单常见问题，请查看文档：电子面单常见问题（旧）

1.500-Internal Server Error

接口入参参数类型不匹配。例如取号接口的callDoorPickUp是boolean类型，不能传空字符串。取号接口的templateId、weight、count等都是number类型，不能加上双引号。tradeOrderInfoList是一个数组，不是对象。sellerName是必填字段，不校验内容准确性但是必须要传。
接口必填参数没有填写。例如取号接口经常有packageInfo.id没有填写。

2.找不到发货地址对应的订购信息

请检查发件人地址（province、city、district、town、detail）、快递公司编码(cpCode)、网点编码(branchCode)、品牌编码(brandCode)、月结卡号(customerCode)等字段和订购接口返回的数据是否一致，所有的字段不能有多余的空格。

对于直营类型的快递一般都要求月结卡号必填，branchCode不能传值，除顺丰外brandCode也不能传值；对于加盟型的快递一般都要求网点编码必填，branchCode和brandCode不能传值；对于顺丰来说，品牌编码brandCode和月结卡号customerCode都必填。

小红书的发件人地址是四级地址，很多开发者漏掉了第四级town，如果查询订购接口返回了town就必须要传town。

当前电子面单有新版和旧版两个版本，旧版订购信息只能用旧版取号，新版订购信息只能用新版取号，有可能是版本弄错了。

订购信息查询为空时还有可能是因为店铺弄错了，有些商家有多个店铺，很多开发者信誓旦旦说没有搞错店铺，最后排查下来就是因为弄错了店铺，截图店铺和调用查询接口的店铺不同。

3.用户信息处理失败

原因一：小红书的收件人信息加密的密钥是跟应用APP绑定在一起的，应用A得到的密文只能在应用A调用取号接口的时候才能解密成功，应用B拿到应用A获取的密文是无法解密的，应用B取号的时候需要额外的加上openAddressId（该字段是order.getOrderDetail订单详情接口返回）参数才可以取号成功，该参数需要应用A获取传递给应用B，但是目前有发现一些上游传过来的oaid是错的和订单并不匹配。

原因二：小红书密文的格式是#xxx#xxx#x##，很多开发者传过来的密文不正确。

原因三：用户修改了地址，导致openAddressId变更，需要上游重新拉取订单信息获取最新的openAddressId。

**注意：**用户信息处理优先级是明文 > 密文 > openAddressId，当传过来的用户信息是错误的密文格式的时候会被判定为明文处理，就会导致取号失败。openAddressId模式取号要求orderChannelsType传值XIAO_HONG_SHU。

4.是否支持店铺之间共享电子面单

小红书目前没有校验当前订单是否属于对应的商家，如果ISV侧能够支持将不同店铺的订单导入到同一家店铺一起打印，在调用电子面单取号接口时确保订单渠道（小红书）、订单号、收件人信息的openAddressId等参数一致即可。

**举例：**用每个店铺自己的accessToken拉取订单，然后用打单店铺的accessToken调用打单接口就可以实现共享取号。ak1代表店铺1的accessToken1，ak2代表店铺2的accessToken2，ak3代表店铺3的acessToken3。

店铺1的ak1拉取订单，用店铺3的ak3调用取号接口，然后用店铺1的ark1发货；
店铺2的ak2拉取订单，用店铺3的ak3调用取号接口，然后用店铺2的ark2发货；
店铺3的ak3拉取订单，用店铺3的ak3调用取号接口，然后用店铺3的ark3发货。

5.代打单业务如何支持

小红书目前没有校验当前订单是否属于对应的商家，如果供应商在小红书平台开店后完成电子面单开通和配置流程，ISV侧能够支持将商家的订单同步给供应商打单发货，isv在调用电子面单取号接口时确保订单渠道（小红书）、订单号、收件人信息的openAddressId等参数一致即可。注意小红书官方代打单功能已经在计划中，该功能上线后可能会增加订单校验。

6.ISV获取订单后推送给WMS打单的场景

需要WMS上游的ERP系统改造将openAddressId这个参数传给WMS，WMS在调用电子面单取号接口时确保小红书订单渠道（orderChannelsType:XIAO_HONG_SHU）、订单号(xhsOrderId)、收件人信息的openAddressId等参数一致即可。

提供一个测试订单的信息给wms测试取号使用，测试的时候用户信息除openAddressId以外其余可为空
xhsOrderId：P694789336444113702
openAddressId：cdc1d228e95df5b37be951323cab81e2

**注意：**因为上面的参数会被多个开发者使用，tradeOrderList需要自己定义为一个其他的值，否则可能导致取号失败；

建议：对于wms来说密文无法取号，所以收件人信息的地址和手机号码建议传空字符，这样可以避免上游ERP推送的密文格式不正确导致取号失败的问题。

7.增值服务取号失败

部分快递公司的增值服务是需要商家申请后才能使用，需要商家登录小红书千帆系统进行申请开通。

增值服务的参数logisticsServices是一个字符串，是一个json格式的字符串，注意对双引号进行转移，格式：{"增值服务1的code":{增值服务1的值},"增值服务2的code":{增值服务2的值} }，例如使用中通保价和特快："logisticsServices":"{"SVC-INSURE":{"value":"100"},"SVC-TIMING-HIGH":{}}"。

8.打印组件相关问题

打印组件是小红书自研，如果遇到使用问题，可以点击右上角的【一键反馈】上传打印日志。

9.打印模板问题

小红书电子面单模板暂时不支持自主编辑，商家只能在小红书商家后台选择平台绘制好的模板。
目前的模板尺寸有：1联-76130、二联-100150、三联-100*180。不同快递公司的模板地址一般是不一样的，只有部分快递公司的模板地址相同。
面单更新接口支持修改电子面单模板，此外打印报文里面的模板地址templateURL也支持修改。
顺丰要求使用顺丰的模板才能取号成功，如果取号时使用了带品牌的取号方式，那么也必须使用带品牌的模板，若两者混用会造成面单信息缺失。
**关于自定义模板：**目前只支持商品名称(item)、订单号(order)、买家留言(buyerMemo)、卖家留言(sellerMemo)等元素，这些数据都需要在发送到打印机接口中传参，参数类型是字符串数组List。如果ISV有其他自定义纯文本需求，建议自行组装拼接好字符串，传到取号接口其中的一个字段实现。如果想要加入除文本以外的其他元素，可以在小红书云打印系统上绘制ISV预设自定义区模板发布以后得到一个线上模板URL，在调用打印组件的时候进行模板URL替换，自定义区域目前只有一联7630和二联10040两种尺寸。

10.关于子母单

目前支持子母单的物流商有：顺丰速递、京东、德邦，其中只有顺丰、德邦支持追加面单。同一个订单号（tradeOrderList）在获取了普通包裹订单号以后，该订单不再支持子母单（普通包裹和子母单包裹混着取有多种结果，强烈不推荐）。揽件以后不再支持追加子单。

**子母单取号方式：**totalPackagesCount传参必须大于等于1，一个包裹号只能拿到一个单号，如果需要获取新的子单号需要重新调用取号接口，或者一次调用中tradeOrderInfoList包含多个元素。子单取号除了objectId和packageInfo.id这两个参数不同以外，其余的参数都要求相同。子母单是基于tradeOrderList来判断是否为同一母单。

顺丰和德邦子母单的第一个单的母单号parentWaybillCode为空，第一个单的单号做为后续子单的母单号。京东的waybillCode全部都是子单号，全部都有母单号parentWaybillCode。

**注意：**京东取号只支持子母件模式，totalPackagesCount不传值的时候会被自动赋值1，不支持追加子单。限制一次最大取件号数量是10个。顺丰取完10个以后，还可以继续追加。

**子母单更新问题：**当前顺丰、德邦的主单支持更新，子单不支持更新；京东只有-1-1-结尾的一单一包裹的子单支持更新。

11.电子面单余额不足

确保商家线下已经联系物流公司进行了充值。此外面单取消后不会立即回充余额，需要等待面单被回收后才会再对商家的余额进行回充。
部分增值服务需要额外号段，需要单独充值（中通与申通生鲜件）。

12.关于批量取号

电子面单不保证批量取号接口的出参顺序，需要通过objectId参数进行识别，该字段和业务无关，需要确保一次请求中每个订单的objcetId不同。
**关于发货地址：**正常每个发货地址都需要分别申请订购后才能取号。如果能够保证快递正常揽件，可以在打印报文的时候使用addData修改发件人地址信息。
顺丰普通面单不支持批量取号。京东取号全部是子母单取号。
新版批量取号会存在部分成功和部分失败的情况。
**取号后又想获取新的单号（还有顺丰、京东取消后重新取号场景）：**xhsOrderId字段传小红书订单号用来解密用户信息，tradeOderList订单号自己加一个后缀用来做取号幂等。对于非京东、顺丰的取号只要包裹号不同就可以获取到新的运单号。历史取号只要不走单没有任何快递轨迹最后会被回收的。
**拆单和合单场景：**取号接口其实不需要关心拆单与合单逻辑，建议取号时xhsOrderId字段传小红书订单号用来解密用户信息，tradeOderList字段传isv自己的拆单id和合单id。
**京东只对接了子母单取号，**无法进行普通单取号
**售后单取号发货：**xhsOrderId字段传售后单returnsId，openAddressId字段传售后详情单查到的openAddressId可以进行取号

13.总对总模式

**适用场景：**电子面单需要支持门店商家的总对总发货模式，商家只需要使用其中一个门店地址订购对总网点，在取号下单时用各自门店的地址分别进行下单。

**支持的快递：**直营型所有快递、加盟型目前支持中通快递。

加盟行快递对总模式接入流程：

\1. 商家、小红书业务、快递三方沟通确认需要走总对总模式；

2.商家在ark后台选择对总网点订购，联系快递审核通过，并让快递配置好对应的对总业务信息；

3.商家告知小红书对总网点编码；

4.商家在isv操作取号打单，新增字段：

4.1 对总网点编码branchCode -必填（接口原有字段）；

4.2 扩展字段extraInfo新增key：

- - store_code-必填客户门店编码--需要快递公司先进行系统配置（快递根据门店编码调度订单）；
  - delivery_type-必填发货类型（门店发货传store，仓发货传warehouse）；
  - pick_code-非必填取件码 --根据实际情况，看是否需要，用于核实包裹。

14.为什么有些传入的产品和接口返回的产品不一致

有些流向不支持某些产品，顺丰会自动转成该流向支持的产品。

15.参数orderId超过最大长度64

orderId 是 tradeOrderList + packageId + accountid 拼起来的，总长度不能超过64位。其中accountid指的是商家电子面单账号ID，当前长度是15位，不需要通过参数接口传入。

16.关于面单更新

更新失败，面单不存在：大多数情况下是由于快递已经揽件导致的，后续会对错误提示做优化。

17.电子面单回收规则

新版电子面单回收规则：

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

快递公司	主动取消回收天数	未走件回收天数	备注
中通	1天	30天
圆通	15天	30天
申通	30天	30天
韵达	40天	40天
极兔	15天	15天	（1）15天没有任何物流轨迹，可以回收充值；（2）15天轨迹中只有快件揽收、入仓扫描、退件登记和拦截件登记、问题件“客户取消寄件”中任意一个或多个轨迹包含带有一条完结标识的，可以回收。

旧版电子面单回收规则

商家主动发取消的面单，自取消之日起15天后，单号统一由系统完成回收。
商家未主动发起取消的面单，无物流详情的面单会在30天后，单号统一由系统完成回收。

18.面单打印异常问题

小红书的面单打印组件是和菜鸟合作，由菜鸟提供面单打印控件技术，请先前往菜鸟云打印答疑知识库自行排查打印问题。常见的打印问题一般都可以通过重启电脑、卸载重装、管理员身份运行等方案来解决

常见问题一：面单打印空白：先检查纸张是否正确，不行的话修改打印模式为 IMAGE 模式

常见问题二：启动失败或者无法连接打印组件

第一步：先关闭退出软件，然后右击软件启动图标，选择【以管理员身份运行】来启动小红书打印组件
第二步：关闭防火墙和杀毒软件，关闭退出小红书打印组件，然后重新打开小红书打印组件，重试后可恢复正常
第三步：重启电脑，小红书打印组件需要用到10818这个端口，有可能被一些程序临时占用了。如果重启后还在报错，就要定位是哪个软件占用了10818端口，把对应的软件进程先杀死。
- windows查看端口占用和杀死进程的命令行如下

#查看端口号所在的进程
netstat -aon|findstr 10818
#杀死进程taskkill -f -pid 进程id

常见问题三：找不到对应的打印机

第一步：先确保其他软件能找到对应的打印机进行打印，如果其他软件也打印不了，请联系打印机厂商进行驱动安装
第二步：重启打印组件或者电脑，然后右击软件启动图标，选择【以管理员身份运行】来启动小红书打印组件

常见问题四：打印列表空白：如果整个打印机列表是空白的，可能是系统的打印服务未启动，百度搜索如何启动电脑打印机服务

19.是否支持其他渠道的订单进行面单打印

支持，但是取号时用户和收货信息需要传明文。

20.测试店铺不能测试电子面单

开放平台上在应用上线前生成的测试店铺不能测试电子面单，需要将应用上线以后才能测试电子面单相关接口.

方式一：小红书千帆系统，开发者自己在小红书上开一个个人店铺用来做测试，小红书搜索『怎么开店』，忽略交保证金部分。

方式二：小红书电子面单系统，适用于不想在小红书上开店的场景。注意小红书电子面单系统的数据和小红书千帆系统的数据不联通，同一个邮箱不要同时注册店铺和小红书千帆系统，否则可能导致授权被覆盖。

注意事项：

a. 小红书测试店铺获取的面单号禁止用来真实走件

b. 京东取号有一些限制，测试寄件人手机号和地址必须为以下列出的地址和手机号：

限定地址：

- - 北京/大兴区/清源街道北京市大兴区亦庄经济开发区给外单的测试地址哈
  - 北京/大兴区/北京经济技术开发区北京市大兴区亦庄经济开发区给快运uat集配站测试面单打印AOI提供的测试地址1
限定手机号为：12993300000、12993300001、12993300010、12993300011

21.部分内网需要配置打印组件访问的资源域名白名单

picasso-static.xiaohongshu.com

qimg.xiaohongshu.com

cloudprint.xiaohongshu.com

fe-static.xhscdn.com

growth-img.xhscdn.com

ep-cloudprint-i1.xhscdn.com

ep-cloudprint-i2.xhscdn.com

pc-infra-api.xiaohongshu.com

apm-fe.xiaohongshu.com

如何关闭防火墙或者配置域名白名单？

自己电脑防火墙，关闭防火墙或者百度搜索如何配置白名单
公司网络限制，联系公司IT配置

22.开放平台相关问题

授权问题，具体的授权规则请查看授权流程：

授权code码：有效期10分钟
accessToken：有效期7天
refreshAccessToken：有效期14天，建议在accessToken过期前30分钟内刷新accessToken，用过一次以后原来的refreshAccessToken立马失效。新的acccessToken和refreshAccessToken会分别重新有7天和14天的有效期，但是要注意在accessToken过期前30分钟内刷新。

根据accessToken和appId获取mercuryUser失败：accessToken expired，说明accessToken已经失效了

根据accessToken和appId获取mercuryUser失败：应用无权限调用该接口，说明应用没有调用电子面单接口的权限，当前只有打单工具、企业ERP、仓储管理、自研应用等这几个类目的应用有电子面单的权限

授权失败目前建议基于错误信息字段的关键字来判断，不要基于错误码401来判断授权失败。

23.接口返回的是code和msg而不是error_code和error_msg

电子面单接口使用了开放平台新框架，在参数类型不匹配、必填参数没传、没有接口权限、accessToken过期等场景下会返回msg和code，建议开发者同时兼容处理一下

物流电子面单code码说明如下，建议优先使用success:true来判断是否成功，如果发现错误码返回不一致的情况可以联系小红书修改

错误码	错误信息
0、200	请求成功
301	请求参数错误
302	请求重复
401	业务处理异常
402	重复提交
501	未知异常
504	网络异常

24.找不到服务描述

查看电子面单对接说明文档附录的产品类型(productCode)和增值服务(logisticsServices)的参数枚举值

25.批量解密接口：加密数据列表，上限100条，批量一次传多少合适?

传入的长度和解密受限没有强相关性，无法给到合适的长度。例如：传入100个解密字符分别来自100个订单，在有50个解密额度的情况下前面的50个订单字符是可以解密成功的，后面的50个字符会解密受限，会报 "解密限额接口调用异常，无法解密，请联系平台"。

26.顺丰返回下单方式不符合

顺丰下单返回【下单方式不符合】错误基本上都是由于产品类型不支持上门取件导致的，例如填舱标快（238）、电商标快不支持上门取件。有些商家的月结卡号和顺丰签有电商标快协议，下单S2会自动转电商标快，不支持上门取件。

27.接口调用超时

平台的接口是保证5s返回结果，很多ISV设置的超时时间是3s，建议改为5s。此外批量取号会增加耗时，建议取号时一次只取1个号。顺丰取号接口性能比较差，耗时容易超过3s。

28.用户信息前面多了或者少了一些字符

开放平台的加密和解密算法是基于订单来加密的，如果加密的订单和解密的订单不一致就可能导致出现这种情况，需要ISV确保传的订单号是获取订单详情时的订单号。一些异常情况，手机号码多了一些字符，或者少了一些字符。

29.关于隐私面单

小红书目前面单上用户信息显示都是脱敏的，暂时不支持隐私小号，短期内暂无迭代计划。

30.订单已生成路由不能申请子单

订单有轨迹以后不允许再申请子单，也不允许取消

31.子单号序号2超过总件数1

目前京东只对接了子母单模板，都是子母单取件模式，同一个订单号不允许二次取号，如果希望二次取号需要传参xhsOrderId传小红书订单号并且tradeOrderList加上一个尾缀

32.顺丰体积传值不生效

对于顺丰子母单取件，需要在extraInfo字段中传入totalVolume，格式："extraInfo":"{"totalVolume": 1000}"

建议顺丰取号的时候同时传volume和extraInfo.totalVolume

33.暂无有效订购关系，请确认快递信息配置

当商家使用小红书官方直送订购了电子面单时，对于京东来说，商家只能使用特惠送（ed-m-0001）或者特惠小件（ed-m-0019）这两种产品类型之一。暂时没有对外提供接口查询官方直送订购的产品类型。识别是否官方直送的方式是查询订购关系接口返回的详细地址是以【-官方直送】结尾的。

34. 重复下单

官方直送业务是根据packageInfo.id做的幂等，要求所有订单的包裹号传值都不一样，并且同一个包裹号不允许重复取号；建议packageInfo.id传值规则为订单号+包裹序号。识别是否官方直送的方式是查询订购关系接口返回的详细地址是以【-官方直送】结尾的。

35.订单中存在商品已进行电子面单打单，请至电子面单发货

在调用发货的接口会报这个错误，是因为商家在小红书官方千帆系统上操作了打单，只允许在千帆系统上【订单】【打单发货】【已打单待发货】页面进行发货

36.送货上门常见问题解答

Q：送货上门支持的快递公司有哪些？

A：目前有顺丰、京东，后续会逐渐接入其他快递公司。

Q：送货上门的订单如果不使用指定的快递公司发货，电子面单取号会报错吗？

A：不会，可以正常取号发货。但未履行相应的服务，后续如果引起消费者投诉，会判罚商家责任，需要商家给消费者赔付10元消费券。

Q：非送货上门的订单合单，还需要传xhsOrderList字段吗？

A：建议传，以后若有合单相关的需求，就不用再改造了。不合单可以不用传这个字段。送货上门的标记不需要ISV传，我们会去查询xhsOrderList（未传值时查询xhsOrderId）中订单的送货上门标识，然后在取号的时候下发给快递公司。

Q：tradeOrderList与xhsOrderList是什么关系？

A：tradeOrderList的作用是取号幂等，不用于业务逻辑，可以传外平台单号。xhsOrderList会用于业务逻辑判断，只能传小红书订单号。

Q：传了xhsOrderList以后还需要传xhsOrderId吗？

A：当前是要求传xhsOrderId的，xhsOrderList传所有的小红书订单号，xhsOrderId可以传其中任意一个小红书订单号。

Q：商家为什么还看不到送货上门服务？

A：送货上门服务是新上线的功能，目前还在灰度内测中，将在5.1假期过后陆续放量，请商家耐心等待平台公告。

37.电子面单取号幂等逻辑是什么

取号幂等是基于tradeOrderList[0] + packageInfo.id 组合进行幂等。对于子母单是基于tradeOrderList[0]关联到同一个母单号。

38.如何区分新版和旧版电子面单

在小红书：

如果是在新版页面，顶部有【切换旧版】按钮，标题是【新版电子面单】，还会有【一键切换】按钮。新版的店铺ID长度是18位，并且是13开头。
如果是旧版页面，顶部有【新版电子面单】链接切换，标题是【旧版电子面单】或者【电子面单】。旧版的店铺ID长度是15位，以10开头。

在快递公司：

渠道来源不一样，旧的渠道来源可能是菜鸟小红书，新版一定是小红书。注意对于中通，小红书旧版的渠道是【小红书线上】，新版的渠道是【小红书】。
新版的店铺ID长度是18位，13开头。旧版的店铺ID长度是15位，以10开头，电子面单账号可以在小红书千帆系统电子面单页面上看到。

39.面单路由信息为空

部分快递公司例如圆通在查询路由超时时就不会返回路由信息，但是打印的面单是可以正常走件的；也有部分情况下是由于地址不明细导致无法出准确的三段码，也可以正常走件。

40.旧版电子面单余额如何处理

方案一：旧版余额较少，全部使用完再切换新版

方案二：旧版余额较多或者旧版已经不能取号了，需要联系快递网点，先将旧版账户余额清退，然后重新充值到新开通的新版电子面单账号

41.电子面单一键切换问题

电子面单一键切换不会对旧版产生任何影响，切换后旧版仍然可以使用。

新版和旧版是完全独立的账号，一键切换后需要等待快递公司审核。

42.模板id和当前面单版本不匹配，请通过面单模板查询接口获取对应面单版本的模板id

批量取号接口的模板ID字段templateId，新版取号时要用新版的模板ID，旧版要用旧版的模板ID。

很多开发者在取号的时候固定写死了旧版的模板ID，所以导致取号失败，取号时建议使用模板查询接口查询得到的模板id。

43.加密数据解密失败，BadPaddingException

旧版取号数据使用旧版打印组件，新版使用新版打印组件，新版和旧版相互独立并且相互不兼容。

当拿着旧版取号密文数据发送到新版打印组件就会报错【加密数据解密失败】。

当拿着新版取号密文数据发送到旧版打印组件就会报错【BadPaddingException:pad block corrupted】。

44.因为网络问题下载模板失败或者网络超时导致打单失败

推荐设置成下面这些主流的公共DNS，如果是ERP系统自己的模板超时，请联系ERP技术支持对模板接口进行性能优化。