文档版本更新记录

版本号	时间	更新内容
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选择此承运商时就是走电子面单流程	获取商家电子面单资料	是
获取运单号	获取运单号	是
修改运单号（仅可以在发货后修改）	修改运单号	否
取消运单号	取消运单号	否
查询可合包的订单信息	查询可合包的订单信息	否
根据订单号查询获取运单成功的运单信息（包含合包成功的订单信息）	根据订单号查询获取运单成功的运单信息（包含合包成功的订单信息）	否
运单发货（或订单发货，订单发货将该订单下的所有运单发货），可支持多个发货	运单发货（或订单发货，订单发货将该订单下的所有运单发货），可支持多个发货	是
获取商家电子面单模板	获取商家电子面单模板	否
更新商家电子面单模板。输入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：请先和店铺确认是否有使用平台提供的标准商品信息表格，若有，请在获取运单号时谨慎传入订单商品数量。若无，请自行在自定义区域打印商品信息及数量（尤其是平台商品数量与实际商品数量不一致的情况）
新增接口及打印组件请求响应样例下载 密码：whrg

四、打印组件

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

1、安装唯品会打印组件

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

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

1.3 沙箱切换方式

2、获取面单数据

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

商家资料下载 密码：abwz

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)

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

请求字段说明：

层级	字段	中文	类型	必填/可选	描述
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	必填
2	customerTemplate	商家自定义区域模板	String	选填	customerTemplate、platformTemplateURL同时有值才自行组合形成打印模板内容，否则走兜底 templateUrl
2	platformTemplateURL	平台模板url	String	选填	customerTemplate、platformTemplateURL同时有值才自行组合形成打印模板内容，否则走兜底 templateUrl
3	templateUrl	模板url	String	必填	url包含了访问的url链接、回调vop的appKey&appsecret与模板识别的相关资料。
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字符串，里面的tmplHeight和tmplWidth 用做打印组件限制纸张大小的
4	printId	打印任务ID	String	必填	打印任务ID，区别每次打印任务
4	customData	自定义数据	Map<String,String>	可选	key：remark（订单备注）, adtxt（提示信息），ext1（扩展信息1），ext2（扩展信息2），ext3（扩展信息3），最多到50
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	可选	区别每次打印任务

电子面单支持承运商

carrier_code	承运商
zhongtong	中通速递
yuantong	圆通速递
shentong	申通快递
yunda	韵达快递
shunfeng	顺丰速运
ems	EMS
jd	京东快递
debangwuliu	德邦快递
annto	安得物流
youzhengguonei	邮政国内小包
shunxinjieda	顺心捷达
tiandihuayu	天地华宇
kuayue	跨越
fengwang	丰网
yimidida	壹米滴答
jtexpress	极兔
subida	速必达
jiuyescm	九曳物流
boyol	贝业新兄弟

附录

常见问题说明及快递增值服务传值说明 密码： dimz
新增接口及打印组件请求响应样例下载 密码：whrg
商家资料下载 密码：abwz
唯品云打印组件操作指南 密码：rwuv