国内外贸网站建设公司,成都市文化馆网站建设,沈阳有什么服务网站,小程序个人主页模板菜鸟打印组件交互协议相关介绍如下#xff1a;
1、打印组件下载地址
https://page.cainiao.com/waybill/cloud_printing/home.html
2、socket连接商品
如果是http的话#xff0c;端口是13529
socket new WebSocket(ws://localhost:13528);
如果是https的话#xff0c…菜鸟打印组件交互协议相关介绍如下
1、打印组件下载地址
https://page.cainiao.com/waybill/cloud_printing/home.html
2、socket连接商品
如果是http的话端口是13529
socket new WebSocket(ws://localhost:13528);
如果是https的话端口是13529
socket new WebSocket(wss://localhost:13529);
3、简介
云打印客户端是以独立进程和打印机交互非作为浏览器插件进行打印。浏览器或其他客户端需要通过 WebSocket协议与云打印客户端进行通信支持javascriptjavac/cpython等常用的语言建议使用对应开发与语言支持的 Websockt 库。若 ISV 的 ERP 系统是B/S结构建议使用如下版本浏览器:chrome 45及以上建议使用chrome的最新版本相关浏览器的极速模式
4、请求协议头格式说明
请求协议头示例如下
{cmd: command,requestID: unique requestID,version: 1.0
}
字段说明: 字段名 类型 说明 是否必须 cmd string 请求的命令名称 是 requestID string 请求的ID用于唯一标识每个请求每个客户端自己保证生成唯一ID如UUID 是 version string 协议当前版本当前为“1.0” 是
响应协议头
{cmd: command,requestID: unique requestID
}
字段说明: 字段名 类型 说明 cmd string 请求的命令名称 requestID string 发送请求中的ID,原封不动返回使客户端能识别出哪个请求对应的响应
5、print 发送打印/预览数据协议
发送打印/预览数据协议(0.x版本)
注因为打印机质量乘次不齐建议 1 个 task 使用 一个 document可以有效避免重打问题
预览流程0.x
打印流程预览流程1.x:
请求协议格式密文数据针对菜鸟电子面单如下:
{cmd: print,requestID: 123458976,version: 1.0,task: {taskID: 7293666,preview: false,printer: ,previewType: pdf,firstDocumentNumber: 10,totalDocumentCount: 100,documents: [{documentID: 0123456789,contents: [{encryptedData:AES:rU904rj6UH2oqfSUb43ZXlOkZaULeerkScS5xbmfjZC78uvsMTa3g6l33hRAz/srsk0TObjJaJI5n4tAPV1uv7szIPQGPDhwD6MKzvTVIfuQCMC8pcUB5S4FmqDhNE45LRVAlaoaI5YK8QmWK1WorhwnPxOFH4Ws/ApobtzDLDJaW6uu1AMEdAejEhRTWL3B1fRhhcDxc3gXDZF9jJUBfb9JZqmocWRu0Fvi/b1BokQx7Xt/NFpJVRI0//NNUQ9b/W4tqGFIbf2IM/Ez1S5hBru5gKGdFzs99ZgCKqtWa0DnOzrZDXroU1mhurtlulE8QbipInu63fkIwn3h9ZSK0sMyV5Jrk5x3MIJDHeW9pc/Tw4TnKTAU134jlGbbpYysa0jBARWRjombeKIFSVfp/zgp15jClClUU1Nz4alTi22LimY2qteQRG6G/rCHiYxPoBRdrtqZZxNSdnKG5yjSdtA2CEL1DJNg1QkFVSSsOuqcHLdrKl6oMRaUN6wM3GQikmKSU/CH4hWCCXxFaJXvBYoSxZ63GrM/dl6D49rCxHJoEVsa2E1TMHLUOnN6CweSM45lcBK19bbCUJDyky6nb1NbxrZGYhmfkrNzE2GNCz4iTAgxJlQxd1gVvS4v5nB7qNfb0Uhy9NTopdumxOS7NXFFg3RFdBfAJ0nLGnxECUvUihBC3pwsLGimrUnIF4174m6J6Ga6cQEPp1LXgtKf5zWJdWHkm2vQhazcAsQC8JJZFb1ESp1vIAvpy0d0YmGrLLzxWNciHlOa7vguFCVF3UbTFe8r1Mxyym9rqNrZDXWRtBija9yeliMERVFuOTRjlc0PVAzveexQmuD4ESTzMZPtbO0jos1EITKhHcV35Na7E4I7bEe3L2u5yuFuzDA5cc8OA8v761xOI70bGXUwvFO2kCCiUFEzI9ksLIDTtydBTA94lf4MYH6m0ziRmAhAgcwm5QJFd2G4JzpFIK4dLuEZamrYUcnHmWzDIgHYIXh6g3S2maFU7dUtwYoerptOTiVg8FxRlUTx30NDTgjm7ll8vEJXHj7yd/gAO3Vm9P54OSMv8wpzX3gtCkvthrkjlToT1jMRNJyuJAeSBf5jruzYLS68inlSE/ehT10zhaiBvaCqojZZ2Ux0JQGhbR/nQ,signature:19d6f7759487e556ddcdd3d499af087080403277b7deed1a951cc3d9a93c42a7e22ccba94ff609976c5d3ceb069b641f541bc9906098438d362cae002dfd823a8654b2b4f655e96317d7f60eef1372bb983a4e3174cc8d321668c49068071eaea873071ed683dd24810e51afc0bc925b7a2445fdbc2034cdffb12cb4719ca6b7,templateURL:http://cloudprint.cainiao.com/template/standard/101/123,ver:waybill_print_secret_version_1},{data: {value: 测试字段值需要配合自定义区变量名},templateURL: http://cloudprint.cainiao.com/template/customArea/440439}]}]}
}
请求协议格式明文数据如下:
{cmd: print,requestID: 123458976,version: 1.0,task: {taskID: 7293666,preview: false,printer: ,previewType: pdf,firstDocumentNumber: 10,totalDocumentCount: 100,documents: [{documentID: 0123456789,contents: [{data: {nick: 张三},templateURL: http://cloudprint.cainiao.com/template/standard/278250/1},{data: {value: 测试字段值需要配合自定义区变量名},templateURL: http://cloudprint.cainiao.com/template/customArea/440439}]}]}
} 字段说明 字段名 类型 说明 是否必须 taskID string 打印机任务ID每个打印任务会分配不同的且唯一的ID在0.x中默认不允许taskID重复若重复则直接返回错误 在1.5.0中当task结构中的idempotent设置为true时不允许taskID重复默认允许重复 是 idempotent bool 1.5.0版本及以后支持 与taskID搭配使用当值为true时taskID不允许重复默认为false 否 notifyType array 打印通知类型:“render”, “print” [“render”] : 仅渲染响应 notify [“print”] : 仅出纸响应 notify ?“render”, “print” : 渲染完成会响应 notify 出纸完成后会响应 notify [] : 不允许 注:如果notifyType没有指定默认为[“render”, “print”] ??在1.x版本中废弃此字段总是会进行通知 否 preview bool 是否预览.true为预览,false为打印 是 printType string 可选dirctPrint或templatePrint 默认为templatePrint当设置为dirctPrint时templateURL可以放入PDF的链接进行PDF打印 否 previewType string 属性取值“pdf” or “image” 预览模式是以pdf还是image方式预览二选一此属性不是必选默认以pdf预览。 否 firstDocumentNumber int task 起始 document 序号 否 totalDocumentCount int task document 总数 否 printer string 打印机名如果为空会使用默认打印机 否 templateURL string 模板文件url 是 signature string 模板与数据的签名 否 documents array 文档数组每个数据表示一页 是 documentID string 文档的唯一ID对于菜鸟标准面单来讲就是面单号;如果是自定义模板需要保证唯一 是 data Json Object 模板需要的打印数据 是
菜鸟打印组件响应
协议格式如下:{cmd:print,requestID:123458976,taskID:1,status:success, //如果是打印表示打印任务提交成功如果是预览表示预览PDF文件生成成功previewURL:http://127.0.0.1/previewxxx.pdf, //如果是预览会返回这个属性表示预览PDF文件的URL地址如果是打印命令不返回此属性
//如果是预览并且预览模式是previewType:image会返回这个属性表示预览图片的URL地址如果是打印命令不返回此属性previewImage: [http://127.0.0.1/preview1.jpg,http://127.0.0.1/preview2.jpg,http://127.0.0.1/preview3.jpg],
//1.x后的菜鸟打印组件版本
urls[url1,url2]
} 字段名 类型 说明 taskID string 打印机任务ID每个打印任务会分配不同的且唯一的ID status string 如果是打印表示打印任务提交成功如果是预览表示预览PDF文件生成成功 previewURL string 可预览的PDF文件URL路径 previewImage string[] 预览image的URL路径是一个字符串数组 urls string[] 1.x后的菜鸟打印组件版本会在预览时返回
注: * 如果是打印命令只是表示将打印任务提交到任务队列会快速返回。 * 如果是预览命令且版本为0.x则需要将预览文件生成才会返回需要一段等待时间。如果是1.x版本则会立即返回一条消息表示任务已提交到任务队列随后当预览文件生成后会再次返回一个消息并携带文件地址
最佳实践
由于网络协议本身的不可靠性建议接入时按照以下规范进行否则可能出现漏打、重复打等情况
发送指令前先检查websock链接的可用性若不可用则重连发送打印指令后等待【任务已提交】的响应此时可以告知用户任务已提交打印保持发送的链接存活不主动关闭持续监听notifyPrintResult消息当接收到失败或者成功后才关闭链接当接收到成功后应修改业务系统中打印任务的状态并提示用户某任务已完成当接收到失败后应修改业务系统中打印任务的状态并提示用户某任务已失败调整任务的taskID和idempotent配置以符合业务预期
6、notifyPrintResult 打印通知
此消息总是由菜鸟打印组件向调用方返回
通知协议格式如下:
{cmd:notifyPrintResult,printer:中通打印机A,taskID:1,taskStatus:printed,printStatus:[{documentID”:”9890000112011”,status:success,msg:if failed,some tips, if success ,nothing”,detail:错误信息的补充描述}]
}
字段解释 字段名 类型 说明 documentID string 文档的唯一ID对于菜鸟标准面单来讲就是面单号;如果是自定义模板需要保证唯一 taskStatus string 任务状态: failed : 失败; rendered: 渲染完成 printed : 出纸完成 ?注当打印出纸之后才会发送通知并且只通知一次 status string 任务状态:success成功;failed 失败,canceled 取消 当一个任务中的一个文档打印失败任务中其他的文档打印状态为“canceled”状态 msg string 如果任务状态为成功或挂起为空如果任务状态为失败则为失败原因概要。 detail string 错误信息的补充描述 printer string 负责打印的打印机名 taskID string 任务ID每个打印任务会分配不同的且唯一的ID
注判断是否打印成功请根据“cmdnotifyPrintResult”、“taskStatus的状态”组合判断
7、 getPrinters 获取打印机列表
请求协议格式如下:
{cmd: getPrinters,requestID: 123458976,version: 1.0
}
响应协议格式如下:
{cmd: getPrinters,requestID: 123458976,defaultPrinter: XX快递打印机,printers: [{name: XX快递打印机},{name: YY物流打印机}]
} 字段名 类型 说明 defaultPrinter string 默认打印机 name string 打印机的名字 8、getPrinterConfig 获取打印机配置
请求协议格式如下:
{cmd:getPrinterConfig,printer:菜鸟打印机,version:1.0,requestID:123456789
}
响应协议格式如下:
{cmd: getPrinterConfig,requestID: 123456789,status: success/failed,msg: 如果出错错误原因,printer: {name: 打印机名称,needTopLogo: false,needBottomLogo: false,horizontalOffset: 1,verticalOffset: 2,forceNoPageMargins: true,autoPageSize: false,orientation: 0,autoOrientation: false,paperSize: {width: 100,height: 180}}
} 字段名 类型 说明 status string 标示命令成功或失败取值“success”或者“failed” msg string 如果出错错误原因 printer.name string 打印机名称 printer.needTopLogo bool 是否需要模板上联的快递logo true为需要 false为不需要 printer.needBottomLogo bool 是否需要模板下联的快递logo true为需要 false为不需要 printer.horizontalOffset float 水平偏移量 printer.verticalOffset float 垂直偏移量 printer.forceNoPageMargins bool 强制设置页面无空边 true为强制设置页面无空边 false为由打印机驱动决定 printer.paperSize.width int 打印机纸张的宽度单位是毫米 printer.paperSize.height int 打印机纸张的高度单位是毫米 printer. autoPageSize bool true自适应纸张大小 false不自适应 printer. orientation int 0纵向 1 横向 printer. autoOrientation bool true按照 orientation 适应纸张方向 false不自适应
9、setPrinterConfig 设置打印机配置
请求协议格式如下:
{cmd: setPrinterConfig,requestID: 123458976,version: 1.0,printer: {name: 菜鸟打印机,needTopLogo: true,needBottomLogo: false,horizontalOffset: 0.5,verticalOffset: 0.7,forceNoPageMargins: true,autoPageSize: false,orientation: 0,autoOrientation: false,paperSize: {width: 100,height: 180}}
} 注参数说明参考 获取打印机配置(getPrinterConfig)
响应协议格式如下:
{cmd:setPrinterConfig,requestID:123458976,status:success,msg:if failed ,some tips, if success,nothing
} 字段名 类型 说明 status string 消息处理结果。success:成功;failed:失败 msg string 如果成功则为空;如果失败则为失败原因
注:如果要保持某个配置不变应省略对应的配置字段。
10、getTaskStatus 获取任务打印任务状态
请求协议格式如下:
{cmd:getTaskStatus,requestID:123458976,version:1.0,taskID:[12311,12312]
} 字段名 类型 说明 是否必须 taskID json数组 打印机任务ID列表 是 响应协议格式如下:
{cmd:getTaskStatus,requestID:123458976printStatus:[{taskID:12312, detailStatus:[{documentID:9890000112011,status:success,msg:if failed ,some tips, if success or pending nothing,printer:中通打印机A}]}]
} 字段名 类型 说明 taskID string 打印机任务ID每个打印任务会分配不同的且唯一的ID documentID string 文档的唯一ID对于菜鸟标准面单来讲就是面单号;如果是自定义模板需要保证唯一 status string 任务状态:success成功;failed失败;pending提交到打印机打印队列 msg string 如果任务状态为成功或挂起为空如果任务状态为失败则为失败原因。 printer string 负责打印的打印机名
11、getGlobalConfig 获取全局配置
请求协议格式如下:
{cmd:getGlobalConfig,requestID:12345678901,version:1.0
}响应协议格式如下:
{cmd:getGlobalConfig,requestID:12345678901,status:success,msg:return nothing when success, return some tips when failed,notifyOnTaskFailure:true,//忽略字体无法显示的问题ignoreFontCanNotDisplay:true
}
字段解释: 字段名 类型 说明 status string 表示命令成功或失败取值“success”或者“failed” msg string 如果出错错误原因 notifyOnTaskFailure bool 打印任务失败时是否需要通知弹出对话框提醒用户打印失败原因并默认暂停当前打印机的打印true为需要false为不需要 ignoreFontCanNotDisplay bool true表示忽略字体无法显示的问题 false则在字体无法显示时会弹窗报错
12、setGlobalConfig 设置全局配置
请求协议格式如下:
{cmd:setGlobalConfig,requestID:12345678901,version:1.0,notifyOnTaskFailure:true,//忽略字体无法显示的问题ignoreFontCanNotDisplay:true
}
响应协议格式如下:
{cmd:setGlobalConfig,requestID:12345678901,status:success,msg:return nothing when success, return some tips when failed
}
字段解释: 字段名 类型 说明 status string 表示命令成功或失败取值“success”或者“failed” msg string 如果出错错误原因 notifyOnTaskFailure bool 打印任务失败时是否需要通知弹出对话框提醒用户打印失败原因并默认暂停当前打印机的打印true为需要false为不需要
13、getAgentInfo 获取客户端版本信息
请求协议格式如下:
{cmd:getAgentInfo,requestID:12345678901,version:1.0
}
响应协议格式如下:
{cmd:getAgentInfo,requestID:12345678901,status:success,msg:return nothing when success, return some tips when failed,version:0.2.8.3
}
字段解释: 字段名 类型 说明 status string 表示命令成功或失败取值“success”或者“failed” msg string 如果出错错误原因 version string 版本号
注意事项
Websocket 建议使用长连接不要每次发送交互请求去创建一个对象。在同打印组件交互过程中的json报文如果文本中包含了特殊字符比如常见的回车引号等需要对特殊字符做转义详细请参考: JSON 。
14、JavaScript使用示例
function doConnect()
{socket new WebSocket(ws://localhost:13528);//如果是https的话端口是13529//socket new WebSocket(wss://localhost:13529);// 打开Socketsocket.onopen function(event){// 监听消息socket.onmessage function(event){console.log(Client received a message,event);};// 监听Socket的关闭socket.onclose function(event){console.log(Client notified socket has closed,event);};};
}
/**** * 获取请求的UUID指定长度和进制,如 * getUUID(8, 2) //01001010 8 character (base2)* getUUID(8, 10) // 47473046 8 character ID (base10)* getUUID(8, 16) // 098F4D35。 8 character ID (base16)* */
function getUUID(len, radix) {var chars 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.split();var uuid [], i;radix radix || chars.length; if (len) {for (i 0; i len; i) uuid[i] chars[0 | Math.random()*radix];} else {var r;uuid[8] uuid[13] uuid[18] uuid[23] -;uuid[14] 4;for (i 0; i 36; i) {if (!uuid[i]) {r 0 | Math.random()*16;uuid[i] chars[(i 19) ? (r 0x3) | 0x8 : r];}}}return uuid.join();
}
/**** 构造request对象*/
function getRequestObject(cmd){var request new Object();request.requestIDgetUUID(8, 16);request.version1.0;request.cmdcmd;return request;
}
/**** 获取自定义区数据以及模板URL* waybillNO 电子面单号*/
function getCustomAreaData(var waybillNO){//获取waybill对应的自定义区的JSON object此处的ajaxGet函数是伪代码var jsonObject ajaxGet(waybillNO);var ret new Object();ret.templateURLjsonObject.content.templateURL;ret.datajsonObject.content.data;return ret;
}
/**** 获取电子面单Json 数据* waybillNO 电子面单号*/
function getWaybillJson(var waybillNO){//获取waybill对应的json object此处的ajaxGet函数是伪代码var jsonObject ajaxGet(waybillNO);return jsonObject;
}
/*** 请求打印机列表demo* */
var request getRequestObject(getPrinters);
webSocket.send(JSON.stringify(request));
/*** 弹窗模式配置打印机* */
var request getRequestObject(printerConfig);
webSocket.send(JSON.stringify(request));
/*** 打印电子面单* printer 指定要使用那台打印机* waybillArray 要打印的电子面单的数组*/
function doPrint(var printer,var waybillArray)
{var request getRequestObject(print); request.task new Object();request.task.taskID getUUID(8,10);request.task.preview false;request.task.printer printer;var documents new Array();for(i0;iwaybillArray.length;i) {var doc new Object();doc.documentID waybillArray[i];var content new Array();var waybillJson getWaybillJson(waybillArray[i]);var customAreaData getCustomAreaData(waybillArray[i]);content.push(waybillJson,customAreaData);doc.content content;documents.push(doc);}request.task.documentsdocuments;socket.send(JSON.stringify(request));
}
/*** 响应请求demo* */
websocket.onmessage function(event){ var response eval(event.data);if (response.cmd getPrinters) {getPrintersHandler(response);//处理打印机列表} else if (response.cmd printerConfig) {printConfigHandler(response);}
};
15、JAVA使用示例
java使用websocket需要引入第三方库 下载地址 。
dependencygroupIdorg.java-websocket/groupIdartifactIdJava-WebSocket/artifactIdversion1.3.0/version
/dependency
自己创建一个websocket管理类需要继承自第三方类库的WebSocketClient:
import java.net.URI;
import java.net.URISyntaxException;import org.java_websocket.client.WebSocketClient;
import org.java_websocket.drafts.Draft;
import org.java_websocket.drafts.Draft_17;
import org.java_websocket.handshake.ServerHandshake;public class WebSocketClientManager extends WebSocketClient {static WebSocketClientManager webSocket null;public static void main(String[] args) throws URISyntaxException {String uri ws://127.0.0.1:13528;webSocket new WebSocketClientManager(new URI(uri), new Draft_17());//建立连接webSocket.connect();}public WebSocketClientManager(URI serverUri, Draft draft) {super(serverUri, draft);}Overridepublic void onOpen(ServerHandshake serverHandshake) {//获取打印机列表String getPrinterListCmd {\requestID\:\12345678901234567890\,\verson\:\1.0\,\cmd\:\getPrinters\};webSocket.send(getPrinterListCmd);//发送打印任务String printCmd 打印任务报文内容过长此处不粘贴;webSocket.send(printCmd);}//WebSocket回调函数Overridepublic void onMessage(String message) {//TODO 对打印服务返回的数据进行处理System.out.println(message);}Overridepublic void onClose(int i, String s, boolean b) {}Overridepublic void onError(Exception e) {}
}
