Home > Document > JITX面单标准&打印组件使用说明

JITX面单标准&打印组件使用说明

接口：JITX获取面单数据接口

顺丰（carrier_code：shunfeng）

面单示例

打印组件

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

1、安装唯品会打印组件

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

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

打印组件图.png {:width="100px" height="100px"}

1.3 沙箱切换方式

沙箱切换.png

2、获取面单数据

2.1 获取面单数据接口：

获取JITX面单数据接口

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)

请求样例下载：JIT&JITX面单组件请求样例提取码: rbtm

请求字段说明：

层级	字段	中文	类型	必填/可选	描述
1	cmd	指令	String	必填	请求的命令名称，具体如下:getPrinters：获取打印机列表。setPrinter：设置默认打印机。print：打印面单
1	requestID	请求的ID	String	必填	请求的ID，用于唯一标识每个请求，每个客户端自己保证生成唯一ID，如UUID
1	task	打印任务	String	必填	打印任务
2	traceId	打印请求ID	String	必填	每次请求唯一，长度不超过20位
2	actionType	打印方式	String	必填	传PRINT: 直接打印 PREVIEW：预览 SAVE: 以文件形式保存到电脑路径下
2	storeId	供应商编码	String	必填	供应商编码
2	channel	业务渠道	String	必填	传600，代表JITX
2	printerName	打印机名称	String	可选	不填时为默认打印机
2	printerMargin	打印机偏移量	String	可选	当次打印的打印机偏移量。格式为 left,right,top,bottom(,为半角英文逗号，数字格式为非负数，两个小数内，不符合格式要求的会处理成0)。例如：0,0,0,0
2	printParamDTO	面单数据对象	JSONObject	必填
3	platformTemplateURL	平台模板url	String	选填	取JITX获取面单数据接口返回的 platform_template_url，并且当customerTemplate、platformTemplateURL同时有值才自行组合形成打印模板内容，否则默认打印标准平台模板内容如果平台运营通知要配置多模板，从面单模板查询服务返回的 platformTemplateURL选择
3	customerTemplate	自定义区域模板	String	选填	自行设计区域模板，customerTemplate仅支持符合http://hiprint.io/design配置的json格式，区域大小宽60高18，并且当customerTemplate、platformTemplateURL同时有值才自行组合形成打印模板内容，否则默认打印标准平台模板内容，注意打印组件8.44以上版本才支持自定义区域
3	templateUrl	模板url	String	必填	取JITX获取面单数据接口返回的 template_url 如果平台运营通知要配置多模板，从面单模板查询服务返回的 templateUrl选择
3	printDatas	面单数据	List	必填	面单数据的列表
4	printData	面单数据	String	必填	取【JITX获取面单数据接口】返回的 order_label，不用解析，直接传入
4	printId	打印任务ID	String	必填	打印任务ID，区别每次打印任务
4	filePath	文件路径	String	条件必填	actionType等于SAVE 时必填，按传入路径存储打印的pdf文件，文件命名为入参的printId
4	customData	自定义内容配置	Map<String,String>	选填	1.标准模板自定义区域支持一个key：goodsInfos，可将内容组装到这个key 输出，支持br换行符。 2. customerTemplate自定义区域自定义格式设计的字段，需要在此传入对应的key和值 3. 新增printPageNum 用于调整面单页面上的打印序号

响应字段说明

层级	字段	中文	类型	必填/可选	描述
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	可选	区别每次打印任务

3.4 获取打印组件当前版本