晟众商城

Appearance

菜鸟打印组件协议详解 ​

1.获取打印机列表getPrinters ​

getPrinters请求协议格式： ​

json
{
	"cmd": "getPrinters",
	"requestID": 0,
	"version": "1.0"
}
{
	"cmd": "getPrinters",
	"requestID": 0,
	"version": "1.0"
}

getPrinters响应协议格式： ​

json
{
    "cmd": "getPrinters",
    "requestID": 0,
    "status": "success",
    "msg": "no error",
    "defaultPrinter": "GP-L80180 Series",
    "printers": [
        {
            "name": "Microsoft XPS Document Writer",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "Adobe PDF",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "Microsoft Print to PDF",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "导出为WPS PDF",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "EPSON LQ-610K",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "Fax",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "GP-L80180 Series",
            "status": "enable",
            "type": "RAW"
        }
    ],
    "errorCode": 0
}
{
    "cmd": "getPrinters",
    "requestID": 0,
    "status": "success",
    "msg": "no error",
    "defaultPrinter": "GP-L80180 Series",
    "printers": [
        {
            "name": "Microsoft XPS Document Writer",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "Adobe PDF",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "Microsoft Print to PDF",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "导出为WPS PDF",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "EPSON LQ-610K",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "Fax",
            "status": "enable",
            "type": "RAW"
        },
        {
            "name": "GP-L80180 Series",
            "status": "enable",
            "type": "RAW"
        }
    ],
    "errorCode": 0
}

getPrinters响应字段说明 ​

字段名类型说明
defaultPrinterstring默认打印机
namestring打印机的名字

2.获取打印机配置getPrinterConfig ​

getPrinterConfig请求协议格式： ​

json
{
  "cmd":"getPrinterConfig",
  "printer":"菜鸟打印机",
  "version":"1.0",
  "requestID":"123456789"
}
{
  "cmd":"getPrinterConfig",
  "printer":"菜鸟打印机",
  "version":"1.0",
  "requestID":"123456789"
}

getPrinterConfig响应协议格式： ​

json
{
	"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
		}
	}
}
{
	"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
		}
	}
}

getPrinterConfig响应字段说明 ​

字段名类型说明
statusstring标示命令成功或失败，取值“success”或者“failed”
msgstring如果出错，错误原因
printer.namestring打印机名称
printer.needTopLogobool是否需要模板上联的快递logo true为需要 false为不需要
printer.needBottomLogobool是否需要模板下联的快递logo true为需要 false为不需要
printer.horizontalOffsetfloat水平偏移量
printer.verticalOffsetfloat垂直偏移量
printer.forceNoPageMarginsbool强制设置页面无空边 true为强制设置页面无空边 false为由打印机驱动决定
printer.paperSize.widthint打印机纸张的宽度，单位是毫米
printer.paperSize.heightint打印机纸张的高度，单位是毫米
printer. autoPageSizebooltrue：自适应纸张大小 false：不自适应
printer. orientationint0：纵向 1： 横向
printer. autoOrientationbooltrue：按照 orientation 适应纸张方向 false：不自适应

3.设置打印机配置setPrinterConfig ​

setPrinterConfig请求协议格式 ​

json
{
	"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
		}
	}
}
{
	"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)

setPrinterConfig响应协议格式 ​

json
{
     "cmd":"setPrinterConfig",
     "requestID":"123458976",
     "status":"success",
     "msg":"if failed ,some tips, if success,nothing"
}
{
     "cmd":"setPrinterConfig",
     "requestID":"123458976",
     "status":"success",
     "msg":"if failed ,some tips, if success,nothing"
}

setPrinterConfig响应字段说明 ​

字段名类型说明
statusstring消息处理结果。success:成功;failed:失败
msgstring如果成功，则为空;如果失败，则为失败原因

注:如果要保持某个配置不变，应省略对应的配置字段。

4. 发送打印/预览数据协议print ​

注：因为打印机质量参差不齐，建议 1 个 task 使用 一个 document，可以有效避免重打问题；

预览流程：

预览流程

打印流程:

打印流程

print请求协议格式（密文数据，针对菜鸟电子面单）如下: ​

{
	"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: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",
                        "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": [{
			"encryptedData":"AES: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",
                        "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"
			}]
		}]
	}
}

print请求协议格式（明文数据）如下: ​

{
	"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"
			}]
		}]
	}
}
{
	"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"
			}]
		}]
	}
}

print请求字段说明： ​

字段名类型说明是否必须
taskIDstring打印机任务ID，每个打印任务会分配不同的且唯一的ID是
notifyTypearray打印通知类型:render，pint；["render"]:仅渲染响应notify；["print"]:仅出纸响应notify；["render","print"]:渲染完成会响应notify&&出纸完成后会响应 notify；[]:不允许；注:如果notifyType没有指定，默认为[“render”, “print”]否
previewbool是否预览.true为预览,false为打印是
previewTypestring属性取值“pdf” or “image” 预览模式，是以pdf还是image方式预览，二选一，此属性不是必选，默认以pdf预览。否
firstDocumentNumberinttask 起始 document 序号否
totalDocumentCountinttask document 总数否
printerstring打印机名，如果为空，会使用默认打印机否
templateURLstring模板文件url是
signaturestring模板与数据的签名否
documentsarray文档数组，每个数据表示一页是
documentIDstring文档的唯一ID，对于菜鸟标准面单来讲，就是面单号;如果是自定义模板，需要保证唯一是
dataJson Object模板需要的打印数据是

print响应协议格式如下: ​

{
    "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
   ]
}
{
    "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
   ]
}

print响应字段说明 ​

字段名类型说明
taskIDstring打印机任务ID，每个打印任务会分配不同的且唯一的ID
statusstring如果是打印，表示打印任务提交成功，如果是预览，表示预览PDF文件生成成功
previewURLstring可预览的PDF文件URL路径
previewImagestring[]预览image的URL路径，是一个字符串数组

注:

  • 如果是打印命令，只是表示将打印任务提交到打印队列，会快速返回。
  • 如果是预览命令，需要将预览文件生成，才会返回，需要一段等待时间。

print更多错误响应示例 ​

json
{
    "cmd": "notifyDocResult",
    "requestID": "154",
    "status": "rendered",
    "printer": "GP-L80180 Series",
    "taskId": "8",
    "documentId": "0123456789",
    "code": 2,
    "detail": "load template http://abcdef.com/inde.html failed Connection timed out: connect",
    "from": {
        "source": "http://abcdef.com/inde.html"
    }
}
{
    "cmd": "notifyDocResult",
    "requestID": "154",
    "status": "rendered",
    "printer": "GP-L80180 Series",
    "taskId": "8",
    "documentId": "0123456789",
    "code": 2,
    "detail": "load template http://abcdef.com/inde.html failed Connection timed out: connect",
    "from": {
        "source": "http://abcdef.com/inde.html"
    }
}
json
{
    "cmd": "notifyTaskResult",
    "requestID": "154",
    "status": "completeFailure",
    "printer": "GP-L80180 Series",
    "taskId": "8",
    "spendTime": {},
    "docs": {
        "0123456789": {
            "cmd": "notifyDocResult",
            "requestID": "154",
            "status": "rendered",
            "printer": "GP-L80180 Series",
            "taskId": "8",
            "documentId": "0123456789",
            "code": 2,
            "detail": "load template http://abcdef.com/inde.html failed Connection timed out: connect",
            "from": {
                "source": "http://abcdef.com/inde.html"
            }
        }
    }
}
{
    "cmd": "notifyTaskResult",
    "requestID": "154",
    "status": "completeFailure",
    "printer": "GP-L80180 Series",
    "taskId": "8",
    "spendTime": {},
    "docs": {
        "0123456789": {
            "cmd": "notifyDocResult",
            "requestID": "154",
            "status": "rendered",
            "printer": "GP-L80180 Series",
            "taskId": "8",
            "documentId": "0123456789",
            "code": 2,
            "detail": "load template http://abcdef.com/inde.html failed Connection timed out: connect",
            "from": {
                "source": "http://abcdef.com/inde.html"
            }
        }
    }
}

print请求协议发送后，更多响应协议格式如下： ​

json
{
  "cmd": "notifyTaskResult",
  "requestID": "167",
  "status": "initial",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358"
}
{
  "cmd": "notifyTaskResult",
  "requestID": "167",
  "status": "initial",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358"
}
json
{
  "cmd": "print",
  "requestID": "167",
  "taskID": "1701767358",
  "status": "success",
  "msg": "no error",
  "errorCode": 0
}
{
  "cmd": "print",
  "requestID": "167",
  "taskID": "1701767358",
  "status": "success",
  "msg": "no error",
  "errorCode": 0
}
json
{
  "cmd": "notifyDocResult",
  "requestID": "167",
  "status": "rendered",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358",
  "documentId": "wx463022894520205312",
  "code": 0,
  "detail": "success"
}
{
  "cmd": "notifyDocResult",
  "requestID": "167",
  "status": "rendered",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358",
  "documentId": "wx463022894520205312",
  "code": 0,
  "detail": "success"
}
json
{
  "cmd": "notifyDocResult",
  "requestID": "167",
  "status": "printed",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358",
  "documentId": "wx463022894520205312",
  "code": 0,
  "detail": "success",
  "spendTime": {
    "total": 1105,
    "downloading": 19,
    "pending": 46,
    "rendering": 1040
  }
}
{
  "cmd": "notifyDocResult",
  "requestID": "167",
  "status": "printed",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358",
  "documentId": "wx463022894520205312",
  "code": 0,
  "detail": "success",
  "spendTime": {
    "total": 1105,
    "downloading": 19,
    "pending": 46,
    "rendering": 1040
  }
}
json
{
  "cmd": "notifyPrintResult",
  "requestID": "167",
  "taskID": "1701767358",
  "status": 0,
  "msg": "no error",
  "taskStatus": "rendered",
  "printer": "EPSON LQ-610K",
  "evaluationSpendTime": 1040,
  "pendingSpendTime": 46,
  "downloadingSpendTime": 19,
  "totalSpendTime": 1105,
  "printStatus": [
    {
      "documentID": "wx463022894520205312",
      "detail": "",
      "msg": "no error",
      "printer": "EPSON LQ-610K",
      "renderingSpendTime": 1040,
      "renderingStartTime": "2023-12-05 17:09:19.288",
      "status": "success"
    }
  ]
}
{
  "cmd": "notifyPrintResult",
  "requestID": "167",
  "taskID": "1701767358",
  "status": 0,
  "msg": "no error",
  "taskStatus": "rendered",
  "printer": "EPSON LQ-610K",
  "evaluationSpendTime": 1040,
  "pendingSpendTime": 46,
  "downloadingSpendTime": 19,
  "totalSpendTime": 1105,
  "printStatus": [
    {
      "documentID": "wx463022894520205312",
      "detail": "",
      "msg": "no error",
      "printer": "EPSON LQ-610K",
      "renderingSpendTime": 1040,
      "renderingStartTime": "2023-12-05 17:09:19.288",
      "status": "success"
    }
  ]
}
json
{
  "cmd": "notifyPrintResult",
  "requestID": "167",
  "taskID": "1701767358",
  "status": 0,
  "msg": "no error",
  "taskStatus": "printed",
  "printer": "EPSON LQ-610K",
  "evaluationSpendTime": 1040,
  "pendingSpendTime": 46,
  "downloadingSpendTime": 19,
  "totalSpendTime": 1105,
  "printStatus": [
    {
      "documentID": "wx463022894520205312",
      "detail": "",
      "msg": "no error",
      "printer": "EPSON LQ-610K",
      "renderingSpendTime": 1040,
      "renderingStartTime": "2023-12-05 17:09:19.288",
      "status": "success"
    }
  ]
}
{
  "cmd": "notifyPrintResult",
  "requestID": "167",
  "taskID": "1701767358",
  "status": 0,
  "msg": "no error",
  "taskStatus": "printed",
  "printer": "EPSON LQ-610K",
  "evaluationSpendTime": 1040,
  "pendingSpendTime": 46,
  "downloadingSpendTime": 19,
  "totalSpendTime": 1105,
  "printStatus": [
    {
      "documentID": "wx463022894520205312",
      "detail": "",
      "msg": "no error",
      "printer": "EPSON LQ-610K",
      "renderingSpendTime": 1040,
      "renderingStartTime": "2023-12-05 17:09:19.288",
      "status": "success"
    }
  ]
}
json
{
  "cmd": "notifyTaskResult",
  "requestID": "167",
  "status": "completeSuccess",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358",
  "spendTime": {
    "downloading": 19,
    "rendering": 1040,
    "total": 1105,
    "pending": 46
  },
  "docs": {
    "wx463022894520205312": {
      "cmd": "notifyDocResult",
      "requestID": "167",
      "status": "printed",
      "printer": "EPSON LQ-610K",
      "taskId": "1701767358",
      "documentId": "wx463022894520205312",
      "code": 0,
      "detail": "success",
      "spendTime": {
        "total": 1105,
        "downloading": 19,
        "pending": 46,
        "rendering": 1040
      }
    }
  }
}
{
  "cmd": "notifyTaskResult",
  "requestID": "167",
  "status": "completeSuccess",
  "printer": "EPSON LQ-610K",
  "taskId": "1701767358",
  "spendTime": {
    "downloading": 19,
    "rendering": 1040,
    "total": 1105,
    "pending": 46
  },
  "docs": {
    "wx463022894520205312": {
      "cmd": "notifyDocResult",
      "requestID": "167",
      "status": "printed",
      "printer": "EPSON LQ-610K",
      "taskId": "1701767358",
      "documentId": "wx463022894520205312",
      "code": 0,
      "detail": "success",
      "spendTime": {
        "total": 1105,
        "downloading": 19,
        "pending": 46,
        "rendering": 1040
      }
    }
  }
}

5. 打印通知notifyPrintResult ​

notifyPrintResult响应协议格式如下: ​

{
     "cmd":"notifyPrintResult",
     "printer":"中通打印机A",
     "taskID":"1",
     "taskStatus":"printed",
     "printStatus":[
        {
           "documentID”:”9890000112011”,
           "status":"success",
           "msg":"if failed,some tips, if success ,nothing”,
           "detail":"错误信息的补充描述"
        }
    ]
}
{
     "cmd":"notifyPrintResult",
     "printer":"中通打印机A",
     "taskID":"1",
     "taskStatus":"printed",
     "printStatus":[
        {
           "documentID”:”9890000112011”,
           "status":"success",
           "msg":"if failed,some tips, if success ,nothing”,
           "detail":"错误信息的补充描述"
        }
    ]
}

notifyPrintResult响应字段说明 ​

字段名类型说明
documentIDstring文档的唯一ID，对于菜鸟标准面单来讲，就是面单号;如果是自定义模板，需要保证唯一
taskStatusstring任务状态: failed : 失败; rendered: 渲染完成 printed : 出纸完成 注：当打印出纸之后才会发送通知并且只通知一次
statusstring任务状态:success成功;failed 失败,canceled 取消 （当一个任务中的一个文档打印失败，任务中其他的文档打印状态为“canceled”状态）
msgstring如果任务状态为成功或挂起为空，如果任务状态为失败，则为失败原因概要。
detailstring错误信息的补充描述
printerstring负责打印的打印机名
taskIDstring任务ID，每个打印任务会分配不同的且唯一的ID

6. 获取任务打印任务状态getTaskStatus ​

getTaskStatus请求协议格式如下: ​

{
    "cmd":"getTaskStatus",
    "requestID":"123458976",
    "version":"1.0",
    "taskID":[
        "12311",
        "12312"
    ]
}
{
    "cmd":"getTaskStatus",
    "requestID":"123458976",
    "version":"1.0",
    "taskID":[
        "12311",
        "12312"
    ]
}

getTaskStatus请求字段说明 ​

字段名类型说明是否必须
taskIDjson数组打印机任务ID列表是

getTaskStatus响应协议格式如下: ​

{
    "cmd":"getTaskStatus",
    "requestID":"123458976"，
    "printStatus":[
        {
            "taskID":"12312", 
            "detailStatus":[
              {
                 "documentID":"9890000112011",
                 "status":"success",
                 "msg":"if failed ,some tips, if success or pending nothing",
                 "printer":"中通打印机A"
              }
            ]
        }
    ]
}
{
    "cmd":"getTaskStatus",
    "requestID":"123458976"，
    "printStatus":[
        {
            "taskID":"12312", 
            "detailStatus":[
              {
                 "documentID":"9890000112011",
                 "status":"success",
                 "msg":"if failed ,some tips, if success or pending nothing",
                 "printer":"中通打印机A"
              }
            ]
        }
    ]
}

getTaskStatus响应字段说明 ​

字段名类型说明
taskIDstring打印机任务ID，每个打印任务会分配不同的且唯一的ID
documentIDstring文档的唯一ID，对于菜鸟标准面单来讲，就是面单号;如果是自定义模板，需要保证唯一
statusstring任务状态:success成功;failed失败;pending，提交到打印机打印队列
msgstring如果任务状态为成功或挂起为空，如果任务状态为失败，则为失败原因。
printerstring负责打印的打印机名

7. 获取全局配置getGlobalConfig ​

getGlobalConfig请求协议格式如下: ​

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

getGlobalConfig响应协议格式如下: ​

{
    "cmd":"getGlobalConfig",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed",
    "notifyOnTaskFailure":true
}
{
    "cmd":"getGlobalConfig",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed",
    "notifyOnTaskFailure":true
}

getGlobalConfig响应字段说明: ​

字段名类型说明
statusstring表示命令成功或失败，取值“success”或者“failed”
msgstring如果出错，错误原因
notifyOnTaskFailurebool打印任务失败时是否需要通知（弹出对话框提醒用户打印失败原因并默认暂停当前打印机的打印），true为需要，false为不需要

8. 设置全局配置setGlobalConfig ​

setGlobalConfig请求协议格式如下: ​

{
    "cmd":"setGlobalConfig",
    "requestID":"12345678901",
    "version":"1.0",
    "notifyOnTaskFailure":true
}
{
    "cmd":"setGlobalConfig",
    "requestID":"12345678901",
    "version":"1.0",
    "notifyOnTaskFailure":true
}

setGlobalConfig响应协议格式如下: ​

{
    "cmd":"setGlobalConfig",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed"
}
{
    "cmd":"setGlobalConfig",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed"
}

setGlobalConfig字段说明: ​

字段名类型说明
statusstring表示命令成功或失败，取值“success”或者“failed”
msgstring如果出错，错误原因
notifyOnTaskFailurebool打印任务失败时是否需要通知（弹出对话框提醒用户打印失败原因并默认暂停当前打印机的打印），true为需要，false为不需要

9. 获取客户端版本信息getAgentInfo ​

getAgentInfo请求协议格式如下: ​

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

getAgentInfo响应协议格式如下: ​

{
    "cmd":"getAgentInfo",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed",
    "version":"0.2.8.3" 
}
{
    "cmd":"getAgentInfo",
    "requestID":"12345678901",
    "status":"success",
    "msg":"return nothing when success, return some tips when failed",
    "version":"0.2.8.3" 
}

getAgentInfo字段说明: ​

字段名类型说明
statusstring表示命令成功或失败，取值“success”或者“failed”
msgstring如果出错，错误原因
versionstring版本号

注意事项 ​

  1. 在使用WebSocket协议与菜鸟打印组件通信时，建议使用长连接，并做好断线重连机制；不要每次发送交互请求都去创建一个对象。
  2. 在同打印组件交互过程中的json报文，如果文本中包含了特殊字符，比如常见的回车，引号等，需要对特殊字符做转义，详细请参考: www.json.org 。