菜鸟打印交互协议 |
您所在的位置：网站首页 › 菜鸟组件打印怎么调尺寸 › 菜鸟打印交互协议 |
|
文档 >>> 菜鸟打印交互协议 菜鸟模板编辑器 菜鸟打印交互协议 菜鸟打印交互协议 简介 协议格式说明 协议详解 1. 请求打印机列表协议(getPrinters) 2. 请求打印机配置协议(getPrinterConfig) 3. 弹窗模式配置打印机协议(printerConfig) 4. 重置打印机配置协议(resetPrinterPreferences) 5. API模式配置打印机协议(setPrinterConfig) 6. 发送打印/预览数据协议(print) 7. 请求任务打印状态协议(getTaskStatus) 8. 获取文档打印状态协议(getDocumentStatus) 9. 打印结果通知协议(notifyPrintResult) 10. 获取全局配置信息(getGlobalConfig) 11. 设置全局配置信息(setGlobalConfig) 12. 获取打印组件版本信息(getAgentInfo) 注意事项 使用示例 1 JavaScript使用示例 2 C++使用示例 2.1 动态链接库 3 JAVA使用示例 4 C#使用示例 5 DELPHI使用示例 简介 菜鸟打印组件是以独立进程和打印机交互，而非作为浏览器插件进行打印。 浏览器或其他客户端需要通过WebSocket协议与菜鸟打印组件进行通信，支持javascript，java，c/c++，python等常用的语言。 若ISV的ERP系统是B/S结构，需要使用以下版本的浏览器来更好的支持WebSocket： IE 10及以上 chrome 45及以上（建议使用chrome的最新版本） Firefox 45及以上（建议使用firefox的最新版本） 协议格式说明 请求协议头：通常，与菜鸟打印组件进行交互，需要发送如下格式的请求协议头： { "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,原封不动返回，使客户端能识别出哪个请求对应的响应 协议详解1. 请求打印机列表协议(getPrinters)请求协议格式如下： { "cmd":"getPrinters", //请求打印机列表命令 "requestID":"123458976", "version"："1.0"}响应协议格式如下： { "cmd":"getPrinters", //需要响应的命令名称，响应获取打印机列表的响应 "requestID":"123458976"， "printers":[ { "name":"XX快递打印机", "status":"enable ", "type":"thermal" }, { "name":"YY物流打印机", "status":"disable", "type":"thermal" } ]} 字段名 类型 说明 name string 打印机的名字 status string 打印机状态 : enable可用; disable不可用 type string 打印机类型 : thermal为热敏打印机; other为除热敏打印机以外的其他类型返回页首 2. 请求打印机配置协议(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,// v0.2.8.3 新增字段 "paperSize":{ "width":100, "height":180 } }} 字段名 类型 说明 status string 标示命令成功或失败，取值“success”或者"failed" msg string 如果出错，错误原因 name string 打印机名称 needTopLogo bool 是否需要模板上联的快递logo,true为需要,false为不需要 needBottomLogo bool 是否需要模板下联的快递logo,true为需要,false为不需要 horizontalOffset float 水平偏移量 verticalOffset float 垂直偏移量 forceNoPageMargins bool 强制设置页面无空边，true为强制设置页面无空边，false为由打印机驱动决定 paperSize object 打印机纸张的宽度和高度，单位是毫米,整形值返回页首 3. 弹窗模式配置打印机协议(printerConfig)请求协议格式如下： { "cmd":"printerConfig", "printer":"中通专用打印机", "requestID":"123458976", "version":"1.0",}响应协议格式如下： { "cmd":"printerConfig", "requestID":"123458976", "printer":"中通专用打印机", "status":"success", //配置成功还是失败 "msg":"if failed ,some tips, if success,nothing"} 字段名 类型 说明 printer string 要配置的打印机 status string 消息处理结果,success:成功; failed:失败 msg string 如果成功，则为空;如果失败，则为失败原因返回页首 4. 重置打印机配置协议(resetPrinterPreferences)此协议是将当前用户的打印机设置重置为系统全局缺省值，如将打印机首选项配置的偏移、纸张尺寸等重置为系统全局缺省值。 此协议当前对奇锐系列的打印机无效。 请求协议格式如下： { "cmd":"resetPrinterPreferences", //重置打印机配置命令 "requestID":"123458976", "version":"1.0", "printer":"菜鸟专用打印机"} 字段名 类型 说明 是否必须 printer string 打印机名 是响应协议格式如下： { "cmd":"resetPrinterPreferences", //需要响应的命令名称，响应重置打印机配置命令的响应 "requestID":"123458976", "status":"success", //重置打印机配置成功还是失败 "msg":"if failed ,some tips, if success,nothing"} 字段名 类型 说明 printer string 打印机名称 status string 标示命令成功或失败，取值“success”或者"failed" msg string 如果出错，错误原因返回页首 5. API模式配置打印机协议(setPrinterConfig)请求协议格式如下： { "cmd":"setPrinterConfig", "requestID":"123458976", "version":”1.0”, "printer": { "name":"菜鸟模板专用打印机" "needTopLogo":true, "needBottomLogo":false, "horizontalOffset":0.5, "verticalOffset":0.7, "forceNoPageMargins":true,// v0.2.8.3 新增字段 "paperSize":{"width":100, "height":180} }} 字段名 类型 说明 是否必须 name string 打印机名 是 needTopLogo bool 是否需要模板上联的快递logo,true为需要,false为不需要；默认为true 否 needBottomLogo bool 是否需要模板下联的快递logo,true为需要,false为不需要；默认为true horizontalOffset float 设置水平偏移量 否 verticalOffset float 设置垂直偏移量 否 forceNoPageMargins bool 强制设置页面无空边，true为强制设置页面无空边，false为由打印机驱动决定 paperSize int 设置打印机纸张的宽度和高度，单位是毫米 否响应协议格式如下： { "cmd":"setPrinterConfig", "requestID":"123458976", "status":"success", "msg":"if failed ,some tips, if success,nothing"} 字段名 类型 说明 status string 消息处理结果。success:成功;failed:失败 msg string 如果成功，则为空;如果失败，则为失败原因* 注：如果要保持某个配置不变，应省略对应的配置字段。 返回页首 6. 发送打印/预览数据协议(print)请求协议格式如下： { "cmd": "print", "requestID": "123458976", "version": "1.0", "task": { "taskID": "1", "preview": false, //如果为true，则是预览模式，为false，则直接打印 "previewType":"pdf/image",//如果是预览模式，是以pdf还是image方式预览，二选一，此属性不是必选，默认以pdf预览。 "printer": "菜鸟模板专用打印机", "notifyMode":"oneByOne/allInOne",//打印结果通知模式，是逐个document通知还是批量一次通知最终打印结果 "firstDocumentNumber":10,// v0.2.8.3 新增：task 起始 document 序号 "totalDocumentCount":100,// v0.2.8.3 本次新增task document 总数 "documents": [ { "documentID": "9890000106027", "contents": [ { "data": { "recipient": { "address": { "city": "北京市", "detail": "花家地社区卫生服务站三层楼我也不知道是哪儿了", "district": "朝阳区", "province": "北京", "town": "望京街道" }, "mobile": "1326443654", "name": "张三", "phone": "057123222" }, "routingInfo": { "consolidation": { "name": "杭州", "code": "hangzhou" }, "origin": { "code": "POSTB" }, "sortation": { "name": "杭州" }, "routeCode": "380D-56-04" }, "sender": { "address": { "city": "北京市", "detail": "花家地社区卫生服务站二层楼我也不知道是哪儿了", "district": "朝阳区", "province": "北京", "town": "望京街道" }, "mobile": "1326443654", "name": "秦疏", "phone": "057123222" }, "shippingOption": { "code": "COD", "services": { "SVC-COD": { "value": "200" } }, "title": "代收货款" }, "waybillCode": "9890000160004" }, "signature": "19d6f7759487e556ddcdd3d499af087080403277b7deed1a951cc3d9a93c42a7e22ccba94ff609976c5d3ceb069b641f541bc9906098438d362cae002dfd823a8654b2b4f655e96317d7f60eef1372bb983a4e3174cc8d321668c49068071eaea873071ed683dd24810e51afc0bc925b7a2445fdbc2034cdffb12cb4719ca6b7", "templateURL": "https://cloudprint.cainiao.com/template/101" }， //自定义模板数据 { "templateURL": "https://cloudprint.cainiao.com/template/802", "data": { "goodsInfo": "我是你要的商品芭比娃娃。。。", } } ] }, {} ] }}下面将进一步说明菜鸟打印组件是如何将这些动态获取的数据填充到模板中的（下面所描述的解析工作均是菜鸟打印组件自动完成，这里只是为了加深理解而进行的说明）。 1、在上述报文中，自定义模板数据为： url：https://cloudprint.cainiao.com/template/802，对应的就是一个动态模板，将这个url发送给菜鸟打印组件后，打印组件会自动解析下载这个模板，其内容如下：。可以看到，有一个动态变量""。（注：这是一个虚拟的url，真实的url应该调用top接口获得） data：也就是要打印的数据，这些会替换模板中的变量。在data中，变量goodsInfo的值为“我是你要的商品芭比娃娃。。。”。2、那么将上述报文发送给菜鸟打印组件后，生成的模板数据如下： 3、可以看到，原始的动态模板中的value值被替换为了"我是你要的商品芭比娃娃。。。"，打印组件将会打印生成后的静态模板。 字段名 类型 说明 是否必须 taskID string 打印机任务ID，每个打印任务会分配不同的且唯一的ID 是 preview bool 是否预览.true为预览,false为打印 是 previewType string 属性取值"pdf" or "image" 预览模式，是以pdf还是image方式预览，二选一，此属性不是必选，默认以pdf预览。 否 printer string 打印机名，如果为空，会使用默认打印机 否 templateURL string 模板文件url 是 signature string 模板与数据的签名 否 documentID string 文档的唯一ID，对于菜鸟标准面单来讲，就是面单号；如果是自定义模板，需要保证唯一 是 data Json Object 模板需要的打印数据 是"previewType":"pdf/image",//如果是预览模式，是以pdf还是image方式预览，二选一，此属性不是必选，默认以pdf预览。 响应协议格式如下： { "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 ]} 字段名 类型 说明 taskID string 打印机任务ID，每个打印任务会分配不同的且唯一的ID status string 如果是打印，表示打印任务提交成功，如果是预览，表示预览PDF文件生成成功 previewURL string 可预览的PDF文件URL路径 previewImage string[] 预览image的URL路径，是一个字符串数组备注: 如果是打印命令，只是表示将打印任务提交到打印队列，会快速返回。 如果是预览命令，需要将预览文件生成，才会返回，需要一段等待时间。 返回页首 7. 请求任务打印状态协议(getTaskStatus)请求协议格式如下： { "cmd":"getTaskStatus", "requestID":"123458976", "version":"1.0", "taskID":[ "12311", "12312" ]} 字段名 类型 说明 是否必须 taskID json数组 打印机任务ID列表 是响应协议格式如下： { "cmd":"getTaskStatus", "requestID":"123458976"， "printStatus":[ { "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 负责打印的打印机名返回页首 8. 获取文档打印状态协议(getDocumentStatus)请求协议格式如下： { "cmd":"getDocumentStatus", "requestID":"123458976", "version":"1.0", "documentIDs":[ "9789173491296", "9890000112011" ]} 字段名 类型 说明 是否必须 documentIDs JSON 数组 文档的唯一ID数组 是响应协议格式如下： { "cmd":"getDocumentStatus", "requestID":"123458976", "printStatus":[ { "documentID”:” 9890000112011”, "status":"success", "msg":"if failed then tips, if success or pending then nothing", "printer":"中通打印机A" } …… ]} 字段名 类型 说明 documentID string 文档的唯一ID，对于菜鸟标准面单来讲，就是面单号；如果是自定义模板，需要保证唯一 status string 面单状态：success成功;failed失败;pending，提交到打印机打印队列 msg string 如果任务状态为成功或挂起为空，如果任务状态为失败，则为失败原因。 printer string 负责打印的打印机名返回页首 9. 打印结果通知协议(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 打印提交协议中notifyMode设置为allInOne，才会存在此属性。只有一个状态printed;当打印出纸之后才会发送通知并且只通知一次。 status string 任务状态:success成功;failed 失败,canceled 取消 （当一个任务中的一个文档打印失败，任务中其他的文档打印状态为"canceled"状态） msg string 如果任务状态为成功或挂起为空，如果任务状态为失败，则为失败原因概要。 detail string 错误信息的补充描述 printer string 负责打印的打印机名 taskID string 任务ID，每个打印任务会分配不同的且唯一的ID注：如果打印提交协议中notifyMode设置为allInOne，本Task中所有的文档打印出纸后一次性通知结果，如果是oneByOne模式，每个文档渲染完成通知一次。 返回页首 10. 获取全局配置信息(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}字段解释： 字段名 类型 说明 status string 表示命令成功或失败，取值“success”或者"failed" msg string 如果出错，错误原因 notifyOnTaskFailure bool 打印任务失败时是否需要通知（弹出对话框提醒用户打印失败原因并默认暂停当前打印机的打印），true为需要，false为不需要返回页首 11. 设置全局配置信息(setGlobalConfig)请求协议格式如下： { "cmd":"setGlobalConfig", "requestID":"12345678901", "version":"1.0", "notifyOnTaskFailure":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为不需要返回页首 12. 获取打印组件版本信息(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 版本号返回页首 注意事项在用JavaScript，C#，C++，delphi，JAVA使用webSocket的过程中，要以全局对象的形式存在，不要每次发送交互请求去创建一个对象，做到webSocket对象重用，和打印组件保持长连接。不然会导致各种意想不到的问题! 在同打印组件交互过程中的json报文，如果文本中包含了特殊字符，比如常见的回车，引号等，需要对特殊字符做转义，详细请参考：http://www.json.org/json-zh.html。 返回页首 使用示例1 JavaScript使用示例var webSocket; //备注：webSocket 是全局对象，不要每次发送请求丢去创建一个，做到webSocket对象重用，和打印组件保持长连接。function doConnect(){ socket = new WebSocket('ws://localhost:13528'); //如果是https的话，端口是13529 //socket = new WebSocket('wss://localhost:13529'); // 打开Socket socket.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 (base=2) * getUUID(8, 10) // "47473046" 8 character ID (base=10) * getUUID(8, 16) // "098F4D35"。 8 character ID (base=16) * */function getUUID(len, radix) { var chars = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'.split(''); var uuid = [], i; radix = radix || chars.length; if (len) { for (i = 0; i |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |