当前位置： 首页 > article >正文

云打印之快手打印组件交互协议

article 2025/1/8 13:23:52

快手打印组件交互协议相关介绍如下：

1、打印组件下载地址

https://docs.qingque.cn/d/home/eZQBMOMSj4mJ5D7Xplofq-p4Y?identityId=2EU7Yr0cDoq

2、 socket连接端口

如果是http的话，端口是16888

socket = new WebSocket('ws://localhost:16888/ks/printer');

如果是https的话，端口是16889

socket = new WebSocket('wss://localhost:16889/ks/printer');

3、简介

  • 云打印客户端是以独立进程和打印机交互（非作为浏览器插件进行打印）。
  • 浏览器或其他客户端需要通过 WebSocket，协议与云打印客户端进行通信，支持javascript，java，c/c++，python等常用的语言（建议使用对应开发与语言支持的 Websockt 库）。
  • 若 ISV 的 ERP 系统是B/S结构，建议使用如下版本浏览器:
  • chrome 45及以上（建议使用chrome的最新版本）；
  • 相关浏览器的极速模式
  • 链接方式：
  • ws连接：ws://localhost:16888/ks/printer
  • wss连接：wss://localhost:16889/ks/printer
  • 最优对接方式：
  • ISV或ERP每次尽可能以10个文档构成一个打印请求给打印组件，等待打印组件返回该次请求的notifyPrintResult（taskId唯一标志），再发送下一个打印请求；

注：一个任务最多只能10个文档，大于10个，请分批请求

4、请求协议头格式说明

4.1 请求协议头

{
	"cmd": "command",
	"requestID": "unique requestID",
	"version": "1.0"
}

字段说明：

字段名

类型

说明

是否必须

cmd

string

请求的命令名称

是

requestID

string

请求的ID，用于唯一标识每个请求，每个客户端自己保证生成唯一ID，如UUID

是

version

string

协议当前版本，当前可以写死为“1.0”

是

4.2 响应协议头

{
	"cmd": "command",
	"requestID": "unique requestID",
  "status": "success",
  "msg": "response说明"
}

 字段说明：

字段名

类型

说明

cmd

string

请求的命令名称

requestID

string

发送请求中的ID,原封不动返回，使客户端能识别出哪个请求对应的响应

status

string

响应状态，success 表示成功，failed 表示失败

msg

String

响应说明（一般是错误信息），非必须

5、getPrinters = 获取打印机列表 

请求协议格式：

{
	"cmd": "getPrinters",
	"requestID": "123458976",
	"version": "1.0"
}

响应协议格式：

{
	"cmd": "getPrinters",
	"requestID": "123458976",
  "status": "success",
  "msg": "if failed ,some tips, if success or pending nothing",
	"defaultPrinter": "XX快递打印机",
	"printers": [
    {
			"name": "XX快递打印机"
		},
		{
			"name": "YY物流打印机"
		}
	]
}

字段说明：

字段名

类型

说明

defaultPrinter

string

默认打印机，为空则说明该打印机脱机

name

string

打印机的名字

6、print = 发送打印数据协议

交互过程：

注意点

  • 注1：推荐2种打印连续下发数据的方式为：
  • 方式一【推荐】：print下发一个task后，收到组件的打印成功响应再继续下发下一个task，即收到notifyPrintResult后，再下发下一个task；
  • 方式二：print下发一个task后，收到组件的print受理成功响应再继续下发下一个task，即收到{"cmd":"print", "requestID":"123458976","taskID":"1","status":"success"} 后再下发一下task。

打印请求协议格式（加密数据）

{
	"cmd": "print",
	"requestID": "123458976",
	"version": "1.0",
	"task": {
		"taskID": "7293666",
		"printer": "xx快递打印机",
    "preview": false,
		"firstDocumentNumber": 10,
		"totalDocumentCount": 100,
		"documents": [{
			"documentID": "0123456789",
			"waybillCode": "SF1236547356",
			"ksOrderFlag": true,
			"contents": [{
					"addData": {
						"senderInfo": {
							"address": {
								"cityName": "南京市",
								"countryCode": "CHN",
								"detailAddress": "软件大道10号华为南研所E区",
								"districtName": "雨花台区",
								"provinceName": "江苏省",
                "streetName": "xxx街道"
							},
							"contact": {
								"mobile": "13282160693",
								"name": "快手"
							}
						}
					},
					"encryptedData": "rU904rj6UH2oqfSUb43+Z+XlOkZaULeerkScS5xbmfjZC78uvsMTa3g6l33hRAz/srsk0TObjJaJI5n4tAPV1uv7szIPQGPDhwD6MK+zvTVIfuQCMC8p+cUB5S4FmqDhNE45LRVAlaoaI5YK8QmWK1WorhwnPxOFH4Ws/ApobtzDLDJaW6uu1AMEdAejEhRTWL3B1fRhhcDxc3gX+DZF9jJUB++fb9JZqmocWRu0Fvi/b1BokQx7Xt/N+FpJVRI0//NNUQ9b/W4tqGFIbf2IM/Ez1S5hBru5gKGdFzs99ZgCKqtWa0DnOzrZDXroU1mhurtlulE8QbipInu63fkIwn3h9ZSK0sMyV5Jrk5x3MIJDHeW9pc/Tw4TnKTAU134jl+GbbpYysa0+jBARWRjombeKIFSVfp/zgp15jClClUU1Nz4alTi22LimY2qteQRG6G/rCHiYxPoBRdrtqZZxNSdnKG5yjSdtA2CEL1DJNg1QkFVSSsOuqcHLdrKl6oMR+aUN6wM3GQikmKSU/CH4hWCCXxFaJXvBYoSxZ63GrM/d+l6D4+9+rCxHJoEVsa2E1TMHLUOnN6CweSM+45lcBK19bbCUJDyky6nb1NbxrZGYhmfkrNzE2GN+Cz4iTAgxJlQxd1gVvS4v5nB7qNfb0Uhy9NTopdumxOS7NXFFg3RFdBfAJ0nLGnxECUvUihBC3pwsLGimrUnIF4174m6J6Ga6cQE+Pp1LXgtKf5zWJdWHkm2vQhazcAsQC8JJZFb1ESp1vIAvpy0d0YmGrLLzxWNciHlOa7vguFCVF3UbTFe8r1Mxyym9rqNrZDXWRtBija9yeliMERVFuOTRjlc0PVAzveexQmuD4ESTzMZPtbO0jos1EITKhHcV35Na7E4I7bEe3L2u5yuFuzDA5cc8OA8v761+xOI70bGXUwvFO2kCCiUFEzI9ksLIDTtydBTA94lf4MYH6m0ziRmAhAgcwm5QJFd2G4JzpFIK4+dLuEZamrYUcnHmWzDIg+HYIXh6g3S2maFU7dUtwYoerptOTiVg8FxRlUTx30NDTgjm7ll8vEJXHj7yd/gAO3Vm9P54OSMv8w+pzX3gtCkvthrkjlToT1jMRNJyuJAeSBf5jruzYLS68inlSE/ehT10zhaiBvaCqojZZ2Ux0JQGhbR/nQ==",
					"signature": "19d6f7759487e556ddcdd3d499af087080403277b7deed1a951cc3d9a93c42a7e22ccba94ff609976c5d3ceb069b641f541bc9906098438d362cae002dfd823a8654b2b4f655e96317d7f60eef1372bb983a4e3174cc8d321668c49068071eaea873071ed683dd24810e51afc0bc925b7a2445fdbc2034cdffb12cb4719ca6b7",
        	"key": "dfsjkhhfksjdhfkfksdfjkf",
					"templateURL": "https://s1-11586.kwimgs.com/kos/nlav11586/EBST-EBSTO6.xml",      // 这个是标准面单的模板链接
					"ver": "waybill_print_secret_version_1"
				},
				{
					"customData": {
						"value": "测试字段值需要配合自定义区变量名"
					},
					"templateURL": "https://s2-11586.kwimgs.com/kos/nlav11586/template/custom/EBCT-EBCTO20.xml"   // 这个是自定义的模板链接
				}
			]
		}]
	}
}

字段说明

字段名

类型

说明

是否必须

备注

taskID

string

打印任务ID，每个打印任务会分配不同的且唯一的ID

是

taskID就是打印组件界面的任务编号需要同一客户端全局唯一（至少过去7天不重复）

firstDocumentNumber

int

task 起始 document 序号，指明该task中第一个document在用户totalDocumentCount的次序。

否

批量打单时会把总数量（如400）以10个面单一组拆成多（如40）个打印任务，每个打印任务的第一单在总数量中的取值就是firstDocumentNumber决定的（如1，11，21等；不传值标准区会打印出0）

totalDocumentCount

int

商家一次性打印的 document 总数

否

批量打单的总数量，如商家一次勾选400单打单，则totalDocumentCount为400（不传值标准区会打印出0）

printer

string

打印机名，不能为空

是

从 获取打印机列表(getPrinters)  交互协议获取的打印机名称列表，选择一个填写到此处

templateURL

string

模板文件url，可以是标准模板和自定义区域模板url

是

标准模板取值为快手开放接口 获取所有标准电子面单模板 返回结果中的 templateUrl

自定义模板取值为快手开放接口 获取自定义区模板列表 返回结果中的 customTemplateUrl

注意：模板文件一定要有xml文件后缀

encryptedData

String

标准模板数据加密后的密文，取号返回数据中printData 字段透传

是

取值为快手开放接口 电子面单取号

返回结果中的 printData

signature

string

模板与数据的签名，取号返回数据中上述printData对应 signature 字段透传

是

取值为快手开放接口 电子面单取号

返回结果中的 signature

key

String

数据加解密秘钥，取号返回数据中上述printData对应 key 字段透传

是

取值为快手开放接口 电子面单取号

返回结果中的 key

ver

String

秘钥版本，取号返回数据中 上述printData对应version 字段透传

是

取值为快手开放接口 电子面单取号

返回结果中的 version

documents

array

文档数组，每个文档表示一个面单数据

是

 

documentID

string

文档的唯一ID，快手标准面单建议使用就是面单号；如果是自定义模板，需要保证唯一

是

同一个task内唯一，必填

waybillCode

string

运单号，一定要填方便问题排查

是

取值为快手开放接口 电子面单取号

返回结果中的 waybillCode

ksOrderFlag

bool

该电子面单对应订单是否是快手订单，true:是，false:其他渠道

是

 

customData

Json Object

自定义区模板打印的数据，自定义模板中占位符一定在 customData 有对应的字段。若customData 没有数据，则自定义对应模板也可不传。

否

 

customData.value

String

自定义区占位符字段

否

 

addData

Object

面单上新的发货地址，传输则会替换原发货地址

否

不建议使用（只改面单地址，不改快递公司的数据）

preview

bool

是否是预览

否

已支持（V1.2.6及之后）

字段举例说明：

  • firstDocumentNumber 和 totalDocumentCount 字段说明：

    • 如用户在isv界面上一次性勾选500订单进行打印，下发格式为一个task中有10个document，则： tototalDocumentCount 为500，第一个 task 的 firstDocumentNumber 为1，第二个 task 的 firstDocumentNumber 为11，以此类推，第50个 task 的 firstDocumentNumber 为491。

    • 如果这两个字段都有值，在渲染过程中会计算当前面单的次序currentDocumentNumber,那么面单上打印出的格式为 currentDocumentNumber/totalDocumentCount。

    • 这样可以保证整批打印出单后面单次序是连续的，有利于排查漏单问题。

打印响应协议格式

{     
  "cmd":"print",     
  "requestID":"123458976",     
  "status":"success", //如果是打印，表示打印任务提交成功
  "msg": "if failed ,some tips, if success or pending nothing",
  "taskID":"1"
}

字段说明

字段名

类型

说明

taskID

string

打印机任务ID，每个打印任务会分配不同的且唯一的ID

status

string

如果是打印，表示打印任务提交成功，success or failed

如果是预览，表示预览是否成功

previewImage

List<String>

若是打印，该字段为null；

若是预览，该字段为预览图片链接列表

 注：打印命令，只是表示将打印任务提交到打印队列，会快速返回。

7、notifyPrintResult = 打印完成通知

通知协议格式

{
  	"cmd": "notifyPrintResult",
    "requestID": "1D4C92A5",
    "status": "success",
    "msg": "if failed ,some tips, if success or pending nothing",  
    "taskID": "9ab81lak91",
    "taskStatus": "printed",
    "printStatus": [{
        "documentID": "14485939587936131",
        "waybillCode": "319000044013574",
        "status": "success",
        "detail": null
    }]
}

字段说明

字段名

类型

说明

requestID

String

先前print请求的requestID

cmd

String

完成通知打印协议标识，固定为 notifyPrintResult

msg

string

响应说明（一般是错误信息），非必须

status

string

响应状态，success 表示响应成功，failed 表示响应失败（一般是有内部异常发生）

注：2.x.x.x以上版本才有

taskID

string

打印请求中打印任务taskID

taskStatus

string

task状态:

     failed : 全部打印失败;

     printed : 全部打印完成

     partPrinted：部分打印完成

 注：当打印出纸之后才会发送通知并且只通知一次

printStatus

List

打印请求中文档的打印结果

       」documentID

string

打印请求中文档的documentID

       」waybillCode

string

运单号

注：2.x.x.x以上版本才有，方便漏单排查

       」status

string

document打印状态:

     success-面单打印完成

     failed-面单打印失败

       」detail

string

document的错误信息的描述（无异常时为空）

8、getClientInfo = 获取客户端版本信息 

请求协议格式

{
    "cmd":"getClientInfo",
    "requestID":"12345678901",
    "version":"1.0"
}

响应协议格式

{
    "cmd":"getClientInfo",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed",
    "currentVersion":"V1.2.3",
  	"latestVersion":"V1.2.4",
  	"latestDownloadUrl": "www.kuaishou.com"
  	"supportedCmds": ["print", "getPrinters"],
  	"osInfo":{"osArch":"","osName":"","osVersion":""}
}

字段解释

字段名

类型

说明

status

string

表示命令成功或失败，取值“success”或者“failed”

msg

string

如果出错，错误原因

currentVersion

string

当前版本号

latestVersion

string

最新版本号

latestDownloadUrl

string

如果最新版高于当前版本，则是最新版链接；否则，为当前版本链接

supportedCmds

json数组

当前版本支持的协议命令，为List转换后的json字符串

osInfo

json string

操作系统信息，arch架构，name名称，version版本

 9、心跳测试

避免websocket连接因超时而自动断开，故提供心跳测试方法：

发送字符串：ping

回复字符串：pong

10、注意事项

Websocket 建议使用长连接，不要每次发送交互请求去创建一个对象。

在同打印组件交互过程中的json报文，如果文本中包含了特殊字符，比如常见的回车，引号等，需要对特殊字符做转义，详细请参考: http://www.json.org/json-zh.html。


http://www.kler.cn/a/471590.html

相关文章：

  • 嵌入式技术之Linux(Ubuntu) 一
  • Chrome访问https页面显示ERR_CERT_INVALID，且无法跳过继续访问
  • 二维数组：求最大元素及其所在的行坐标及列坐标（PTA）C语言
  • BloombergGPT: A Large Language Model for Finance——面向金融领域的大语言模型
  • 概率基本概念 --- 离散型随机变量实例
  • 炸弹 (boom.c)
  • jenkins入门5 Manage Jenkins
  • PyQt5 UI混合开发，控件的提升
  • Travis CI/CD 功能详解
  • ES中的仓库和快照
  • 快速排序(霍尔法)，冒泡排序 【C语言】
  • PHP：PHP脚本通过正则表达式动态修改指定文件下的php文件的sql内容加入指定条件enable_flag = ‘Y‘(“Y“)
  • JSON Schema属性使用汇总
  • Python入门教程 —— 文件操作
  • 对比式机器学习揭示了跨物种共享和特异性的脑功能结构|文献速递-视觉大模型医疗图像应用
  • AI生成前端页面：解放前端开发，拥抱AI时代的高效
  • 【深入理解Mysql】
  • 《Python趣味编程》专栏介绍与专栏目录
  • 常用存储器介绍
  • ros2-4.1 服务通信介绍
  • 【git命令】--- git经典常用操作命令大全
  • 实时计算 Flink 版：赋能数据驱动，让决策快人一步
  • 英语外刊写作积累（2024.09）
  • JavaWeb—Servlet详解
  • Unigui基于vue+elementui的自研框架
  • JVM一之类加载子系统