文档版本更新记录

版本号	时间	更新内容
0.1	2021-11-2	创建
0.2	2021-11-30	补充流程图及相关接口
1.0	2021-12-06	增加验收要求，正式发布
1.1	2022-02-21	取消多包裹商品数量校验，补充相关说明
1.2	2022-03-04	补充所有快递增值服务传值样例及取值
1.3	2022-03-24	新增更新商家电子面单模板接口
1.4	2022-06-23	发布自更新版打印组件：下载新打印组件
1.5	2022-11-28	更新打印组件请求参数及沙箱切换方式
1.6	2023-01-13	更新对接流程图，打印组件请求方式

一、工信部安全改造方案

1. 背景

国家出台了个人信息保护和数据安全相关的法律法规，对保障消费者个人信息权益、规范数据处理活动提出了更明确的责任要求。平台将启动订单处理链路的消费者敏感信息保护方案，对涉及消费者个人敏感信息采取加密（不允许解密）措施。

2. 简述

2.1 从唯品会平台获取的订单会员敏感信息（收件人姓名、收件人手机、收件人电话、地址等）均为密文数据，不允许解密；
2.2 订单的发货履约需要通过唯品会平台获取电子面单；
2.3 包裹面单通过唯品会面单打印组件进行打印

二、对接流程图

接口新增变动情况

1. getOrders

字段	类型	是否必须	描述
hebao_identification_code	String	否	合包识别码
is_create_transport	Byte	否	是否可获取电子面单
is_ship_or_cancel	Byte	否	可发货，可取消
is_print	Byte	否	是否可打印电子面单

2. getOrderDetail

字段	类型	是否必须	描述
transport_no	String	否	运单号
carriers_name	String	否	承运商
carriers_code	String	否	承运商编码
amount	Integer	否	数量
is_print	Byte	否	是否已打印面单
stat	Byte	否	状态 1：已获取运单 2：已发货

3. 新增的接口

接口描述	接口链接	是否必须使用
获取商家电子面单资料 1、以仓 + 承运商商纬度来定义，根据店铺ID在平台服务拿到此店下的开通电子面单的仓+ 承运商； 2、平台仓+ 承运商对应回ISV里的 承运商，定义为支持电子面单流程； 3、商家在ISV选择此承运商时就是走电子面单流程	获取商家电子面单资料	是
获取运单号	获取运单号	是
修改运单号（仅可以在发货后修改）	修改运单号	否
取消运单号	取消运单号	否
查询可合包的订单信息	查询可合包的订单信息	否
根据订单号查询获取运单成功的运单信息（包含合包成功的订单信息）	根据订单号查询获取运单成功的运单信息（包含合包成功的订单信息）	否
运单发货（或订单发货，订单发货将该订单下的所有运单发货），可支持多个发货	运单发货（或订单发货，订单发货将该订单下的所有运单发货），可支持多个发货	是
获取商家电子面单模板（同一个快递存在多个模板时，可以通过此接口查到对应模板的templateUrl 用于调用打印组件）	获取商家电子面单模板	否
更新商家电子面单模板。输入tmplContent的JSON可参考hiprint：hiprint Demo	更新商家电子面单模板	否
获取打印数据	获取给打印组件的打印数据	是
通过token获取商家ID（store_id）	通过token获取商家ID	否
运单余额查询	运单余额查询	否

1单多包裹获取运单号说明

场景	获取运单号字段传值	备注
1个订单1个商品1个包裹发货	package_type:1	单包裹可不传包裹明细（packages)
1个订单2个商品1个包裹发货	package_type:1	单包裹可不传包裹明细（packages)
1个订单1个商品2个包裹发货	package_type:2，包裹明细需要传入，1个package对应1个运单号	1.不传商品明细goods，此时面单的商品表格的商品数量会是0。 2. 传商品明细goods，此时面单的商品表格的商品数量与传入数量一致，且数量将会和订单商品明细的数量比对，进行强检验
1个订单2个商品3个包裹发货	package_type:2，包裹明细需要传入，1个package对应1个运单号	1.不传商品明细goods，此时面单的商品表格的商品数量会是0。 2. 传商品明细goods，此时面单的商品表格的商品数量与传入数量一致，且数量将会和订单商品明细的数量比对，进行强检验

PS：请先和店铺确认是否有使用平台提供的标准商品信息表格，若有，请在获取运单号时谨慎传入订单商品数量。若无，请自行在自定义区域打印商品信息及数量（尤其是平台商品数量与实际商品数量不一致的情况）
新增接口及打印组件请求响应样例下载 密码：dyzz

四、打印组件

打印组件下载：唯品会打印组件下载

1、安装唯品会打印组件

1.1 下载打印组件后，直接打开

1.2 选择使用的打印机（出现下面的页面代表组件已在运行）

1.3 沙箱切换方式

2、获取面单数据

2.1 需要店铺先在store.vip.com先创建自己的模板，并关联要用的平台模板##

商家资料下载 密码：azym

2.2 获取面单数据接口：

获取面单数据接口

3、统一请求协议启用打印机

请求地址： ws://127.0.0.1:12233
请求通用协议头

字段名	类型	说明	是否必须
cmd	string	请求的命令名称，具体如下:getPrinters：获取打印机列表; setPrinter：设置默认打印机; print：打印面单	是
requestID	string	请求的ID，用于唯一标识每个请求，每个客户端自己保证生成唯一ID，如UUID	是

响应通用协议头

字段名	类型	说明
cmd	string	请求的命令名称 (setPrinter、getPrinters、print)
requestID	string	发送请求中的ID,原封不动返回，使客户端能识别出哪个请求对应的响应
code	int	200: 成功； 201：存在打印失败的数据；202：参数无效；203：业务参数缺失；204：面单渲染失败；500：系统处理异常；9999：未知异常
msg	string	返回信息

3.1 获取打印机列表(getPrinters)

请求示例:
{ "cmd": "getPrinters", "requestID": "123458976" }
响应示例:
{ "cmd": "getPrinters", "requestID": "123458976", "code": 200, "defaultPrinter": "XX快递打印机", "printers": [{ "name": "XX快递打印机" }, { "name": "YY物流打印机" }] }

字段名	类型	说明
defaultPrinter	string	默认打印机
name	string	打印机的名字

3.2 设置默认打印机(setPrinter)

请求示例:
{ "cmd": "setPrinter", "requestID": "147258369", "printer": "XX快递打印机" , "printerMargin": "10,0,0,0" }

字段名	类型	说明
printer	string	打印机的名字
printerMargin	string	非必填，持久性修改，打印机的偏移量。格式为 left,right,top,bottom(,为半角英文逗号，数字格式为非负数，两个小数内，不符合格式要求的会处理成0)。例如：0,0,0,0

成功响应示例:
{ "cmd": "setPrinter", "requestID": "147258369", "code": 200, "msg": "设置默认打印机成功" "printer": "当前打印机" , "printerMargin": "10,0,0,0" }
失败响应示例:
{ "cmd": "setPrinter", "requestID": "147258369", "code":202, "msg": "设置默认打印机失败，请检查传入参数是否为可用打印机名称" }

3.3 打印面单(print)

详细请求响应样例请参考：新增接口及打印组件请求响应样例下载 密码：dyzz

请求字段说明：

层级	字段	中文	类型	必填/可选	描述
1	cmd	指令	String	必填	请求的命令名称，具体如下:getPrinters：获取打印机列表。setPrinter：设置默认打印机。print：打印面单
1	requestID	请求的ID	String	必填	请求的ID，用于唯一标识每个请求，每个客户端自己保证生成唯一ID，如UUID
1	task	打印任务	List	必填	打印任务dto，json对象
2	traceId	打印请求ID	String	必填	每次请求唯一，长度不超过20位
2	storeId	商家ID	String	必填	商家的ID，ST开头的
2	printerName	打印机名称	String	可选	不填时为默认打印机
2	printerMargin	打印机偏移量	String	可选	当次打印的打印机偏移量。格式为 left,right,top,bottom(,为半角英文逗号，数字格式为非负数，两个小数内，不符合格式要求的会处理成0)。例如：0,0,0,0
2	printParamDTO	运单列表	PrintParamDTO	必填
3	customerTemplate	商家自定义区域模板	String	选填	自行设计区域模板，customerTemplate仅支持符合http://hiprint.io/design配置的json格式，并且当customerTemplate、platformTemplateURL同时有值才自行组合自定义店铺模板，否则取商家后台配置的店铺模板
3	platformTemplateURL	平台模板url	String	选填	【获取给打印组件的打印数据】返回的 platformTemplateURL，并且当customerTemplate、platformTemplateURL同时有值才组合成自定义店铺模板，否则取商家后台配置的店铺模板
3	templateUrl	模板url	String	必填	取【获取给打印组件的打印数据】返回的 template_url
3	senderData	发货人信息	Map<String,String>	可选	key：name（发货联系人），mobile（移动电话），tel（电话），address（发货地址）。例如:需要对sender.tel进行替换，那需要senderData.put("tel","期望值")
3	printDatas	面单数据	List	必填	面单数据的数组
3	printId	打印任务ID	String	选填	建议带上，帮助区别每次打印任务
4	printData	面单数据	String	必填	面单数据的json串。printData的Json字符串
4	printId	打印任务ID	String	必填	打印任务ID，区别每次打印任务
4	customData	自定义数据	Map<String,String>	可选	1. key：remark（订单备注）, adtxt（提示信息），ext1（扩展信息1），ext2（扩展信息2），ext3（扩展信息3），最多到50，对应商家后台配置的店铺模板打印元素选的字段名 2. customerTemplate自定义区域自定义格式设计的字段，需要在此传入对应的key和值
4	orderSenderData	订单维度的发货人信息	Map<String,String>	可选	类似senderData

响应字段说明

层级	字段	中文	类型	必填/可选	描述
1	cmd	请求命令	String	必填	请求命令
1	traceId	打印请求ID	String	可选	每次请求唯一（返回你入参的traceId）
1	code	响应结果	String	必填	枚举值 ： 200：打印成功， 201：存在打印失败的数据， 202：参数格式问题 （传参不为JSON，或传参缺少必填参数等）， 203：业务参数缺失（例如店铺缺少密钥，根据templateUrl找不到有效的模板信息），500 ：系统处理异常
1	total	传入打印数据数	int	可选
1	requestID	请求ID	String	可选	原封不动返回
1	msg	错误描述	String	可选
1	details	打印结果	String	可选	打印结果
2	row	打印数据行号	int	可选	标识哪一行，避免printId不传的时候区分不了
2	status	打印状态	String	可选	success:成功;fail:失败
2	msg	打印信息	String	可选
2	printId	打印ID	String	可选	区别每次打印任务

电子面单支持承运商

电子面单支持承运商

附录

文件下载 密码：gyrd
常见问题说明及快递增值服务传值说明 密码：gyrd