# 协议介绍
云打印接入协议主要描述了云打印场景下打印机设备与云打印应用如何通过数据交互实现设备信息上报、打印任务下发执行等云打印关键业务。
# 接入流程
根据设备与应用的指令通信流程，在设备业务功能范围确定后，建议按照如下步骤完成协议开发:
# 指令功能
# 设备信息同步
# 功能描述
云打印应用需要实时掌握打印机设备的最新状态信息，包括：网络信息、固件版本、墨盒信息、设备故障状态信息等，用于显示和状态业务处理。
# 设备信息上报指令
当设备端状态信息发生变化时，设备应主动调用本指令上报最新的设备状态数据。
提示
以下情况设备都应主动使用本指令向应用上报设备最新信息：
- 重新接入平台
- 设备信息发生变化（网络信息、墨量信息、打印头信息、固件版本、设备状态（故障，繁忙，就绪）等）
- 设备绑定新应用
- 应用主动查询（收到设备信息查询指令）
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "printer_push_report_info",
"payload": {
"printer_name": "Deli P2500DW-3a2f",
"work_status": "error",
"firmware_version": "HD_2.00.014",
"error_code": 4611,
"error_msg": "设备故障，重启/联系客服",
"error_time": 1503025335,
"network_mode": "WLAN",
"wifi_signal":{
"wifi_rssi":-35,
"wifi_signal_level":1,
"wifi_signal_level_describe":"强"
},
"ssid": "DELI",
"printer_ip": "172.193.12.11",
"mac_address": "EC:F0:0E:84:36:FE",
"total_page_count": 10,
"total_paper_count": 7,
"error_paper_count": 0,
"printheads":[{
"printhead_sn":"PXJ510",
"printhead_status":"0",
"printhead_status_des": "正常",
}],
"inkboxs": [{
"inkbox_sn": "123123",
"inkbox_status": "0",
"inkbox_type":"K",
"inkbox_status_des": "正常",
"inkbox_colors": [{
"color": "black",
"toner_total_count":10000,
"toner_remain_count":9000,
"toner_remain": 90
}]
}]
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
其中cmd固定为printer_push_report_info表示设备信息上报指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| printer_name | 字符串 | Y | 设备当前名称，没有则传设备编号 |
| work_status | 字符串 | Y | 设备状态：idle-就绪，busy-繁忙，error-故障 |
| firmware_version | 字符串 | Y | 设备当前固件版本 |
| error_code | 字符串 | N | 设备故障错误码，错误码请参照设备故障错误码 |
| error_msg | 字符串 | N | 设备故障错误描述 |
| error_time | 字符串 | N | 故障发生时间，精确到秒，如果没有故障 默认为0 |
| network_mode | 字符串 | Y | 设备当前连接网络模式： WLAN-无线，MOBILE-移动网络，LAN-有线，BLUETOOTH-蓝牙 |
| wifi_signal | json对象 | N | wifi_signal为wifi信号对象，WLAN连接时必传。 |
| ssid | 字符串 | N | WIFI的ssid名称，WLAN连接必传。 |
| printer_ip | 字符串 | N | ip地址 |
| mac_address | 字符串 | N | mac地址 |
| total_page_count | 字符串 | Y | 设备总打印面数，累计 |
| total_paper_count | 字符串 | Y | 打印纸张数，累计 |
| error_paper_count | 字符串 | Y | 打印错误纸张数：卡纸等。累计 |
| printheads | json数组 | Y | printhead是喷头对象 |
| inkboxs | json数组 | Y | inkbox是墨盒对象（碳粉盒 or 墨水盒）表示一个更换的整体 |
wifi_signalwifi信号对象参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| wifi_rssi | 字符串 | Y | wifi网络接受信号强度，WLAN网络必传。一般信号强度在-30~-120之间。 |
| wifi_signal_level | 字符串 | Y | 当前wifi信号等级，从1开始，等级越小越高。等级级别数产品定义，默认分5个等级 |
| wifi_signal_level_describe | 字符串 | Y | 当前wifi信号等级描述显示。产品定义保持和打印机显示一致，可参考：强，良好，一般，较差，无信号。 |
print_page_info打印页数信息对象参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| total_printed_page_count | 字符串 | Y | 收到的总页数，包含空页面。 |
| actual_printed_page_count | 字符串 | Y | 实际打印页数，不包含空页面。 |
| total_printed_paper_count | 字符串 | N | 打印纸张数。 |
printhead喷头对象参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| printhead_sn | 字符串 | N | 打印头编号，有编号需传 |
| printhead_status | 字符串 | Y | 打印头状态： 0-正常， -1 打印头未初始化校准， -99其他故障错误 |
| printhead_status_des | 字符串 | Y | 状态描述，当状态为**-99**时，返回具体故障的描述。 |
inkbox墨盒/硒鼓对象参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| inkbox_sn | 字符串 | N | 墨盒/硒鼓编号，有编号需传 |
| inkbox_type | 字符串 | N | 新增字段，墨盒类型： “CMYK”- 黑白彩色一体，"K"-黑色，"CMY"-彩色，“C”-青色，“M”-品红，”Y“-黄色 |
| inkbox_status | 字符串 | Y | 墨盒/硒鼓状态： 0-正常， -1 墨盒墨量低， -2-墨盒未安装 -99其他故障错误 |
| inkbox_status_des | 字符串 | Y | 状态描述，当状态为**-99**时，返回具体故障的描述。 |
| inkbox_colors | inkbox_color列表 | Y | inkbox_color 墨盒/硒鼓颜料的信息列表 |
关于墨盒/硒鼓类型
一个墨盒/硒鼓表示一个单独更换的整体。常见的墨盒/硒鼓类型有4种：
- 黑白彩色一体墨盒/硒鼓，数量1个，类型为："CMYK"。
- 黑白+彩色墨盒/硒鼓，数量2个墨盒，类型分别为：“K”、"CMY"。
- 四单色墨盒/硒鼓，数量4个墨盒，类型分别为：“K”、"C"、"M"、"Y"。
- 黑白单色墨盒/硒鼓，数量1个，类型为："K"
inkbox_color颜料对象参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| color | 字符串 | Y | cmyk颜色值：cyan-青色，magenta-品红，yellow-黄色，black-黑色 |
| toner_total_count | 整数 | N | 新增字段，碳粉（墨水）当前剩余总量，墨量精确计量单位 |
| toner_remain_count | 整数 | N | 新增字段，碳粉（墨水）当前剩余量，墨量精确计量单位 |
| toner_remain | 浮点型 | Y | 碳粉（墨水）剩余百分比，90.00代表90.00%，可精确2位小数。 |
应用收到请求后，应在同一消息上下文向设备返回如下确认消息：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584103546,
"action": 301,
"data": {
"cmd": "printer_push_report_info"
}
}
2
3
4
5
6
7
8
9
10
# 设备信息查询指令
应用可通过本指令主动要求设备上报设备最新信息。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584103546,
"action": 301,
"data": {
"cmd": "server_push_report_info"
}
}
2
3
4
5
6
7
8
9
10
其中cmd固定为server_push_report_info表示设备信息查询指令，无payload信息。
设备收到查询请求后，通过设备信息上报指令上报最新的设备信息。
# 云打印
# 功能描述
应用可以通过云打印功能向设备发起云打印指令实现打印机远程打印文件。
云打印操作流程示意如下：
# 打印任务通知指令
当用户提交的文件打印任务报文转换成功后，应用会通过本指令通知设备有新的打印任务。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_task_add",
"payload": {
"task_type": "print"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_task_add表示打印任务通知指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_type | 字符串 | Y | 任务类型：print-打印任务 |
设备收到请求后，应第一时间在同一消息上下文向应用返回如下确认消息，避免应用频繁重复发送通知。
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"action": 300,
"time": 1584079078,
"data": {
"cmd": "server_push_task_add"
}
}
2
3
4
5
6
7
8
9
10
# 打印任务执行指令
当打印机处于空闲可打印的状态时，可以通过本指令主动向应用拉取可以打印的任务。
提示
为了让打印机能够及时执行打印任务，在以下情况下打印机应主动调用本指令拉取新的打印任务：
- 设备已经被激活的情况下每次接入平台时；
- 当设备收到打印任务通知指令；
- 当设备由故障或繁忙状态下恢复为空闲可打印状态时；
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "printer_push_task_execute"
}
}
2
3
4
5
6
7
8
9
10
其中cmd固定为printer_push_task_execute表示打印任务执行指令，请求无payload信息。
云打印应用服务收到该请求后，会将排队中的第一个未分配的任务下发给打印机设备。响应结果如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584103546,
"action": 301,
"data": {
"cmd": "server_push_task_execute",
"payload": {
"task_status": "1",
"task_id": "P4429f8e8d3b1443bbc6ca04619883884",
"task_type": "print",
"task_info": {
"download_url": "https://domain/123"
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
响应payload参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_status | 字符串 | Y | 是否有可执行任务：0-没有任务，1-有任务 |
| task_id | 字符串 | N | 任务ID。有任务时返回 |
| task_type | 字符串 | N | 任务类型：print-打印。有任务时返回 |
| task_info | json对象 | N | 任务详情：不同任务类型对象内容不同。目前仅支持打印任务类型，其他任务类型暂不支持。 |
关于任务详情task_info的格式，说明如下：
- 当
task_type为print时，格式如下：
{
"download_url": "https://domain/123"
}
2
3
其中，各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| download_url | 字符串 | Y | 打印任务PDL报文下载地址 |
# 打印任务进度上报指令
设备开始执行打印任务后，可通过本指令向云打印应用实时上报打印任务的执行进度和状态。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"action": 300,
"time": 1584091154,
"data": {
"cmd": "printer_push_print_progress",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d",
"print_status": "printing",
"error_code": "",
"error_msg": "",
"error_cause": "",
"printed_page_count": 0,
"printed_paper_count": 0
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
其中cmd固定为printer_push_print_progress表示打印任务进度上报指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务ID |
| print_status | 字符串 | Y | 任务状态：queue-排队等待， printing-打印中，pause-暂停，finish-成功，fail-失败，cancel-取消。 |
| error_code | 字符串 | N | 错误码，故障/异常必填，详细描述见下面异常情况说明 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
| printed_page_count | 字符串 | Y | 已打印页数（面数） |
| printed_paper_count | 字符串 | Y | 已打印成功的纸张数 |
关于打印任务状态上报
打印任务状态print_status的具体说明如下：
- 准备开始执行打印任务时，设备因故无法启动打印，返回
print_status为queue，error_code、error_msg见异常情况说明； - 设备开始执行打印后，返回
print_status为printing； - 打印过程中，每打印完一页时，返回
print_status为printing，printed_page_count为已打印页数，printed_paper_count为已打印纸张数； - 打印过程中，设备出现临时可恢复类型的打印故障时（例如缺纸），返回
print_status为pause，printed_page_count为已打印页数，printed_paper_count为已打印纸张数,error_code、error_msg见异常情况说明； - 打印任务全部完成后，返回
print_status为finish，printed_page_count为已打印页数，printed_paper_count为已打印纸张数； - 打印任务出现失败终止后，返回
print_status为fail，printed_page_count为已打印页数，printed_paper_count为已打印纸张数,error_code、error_msg见异常情况说明； - 打印过程中，用户在设备或应用端主动取消了打印后，返回
print_status为cancel，printed_page_count为已打印页数，printed_paper_count为已打印纸张数；
异常情况说明
- 如果收到云打印指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务
排队等候。 - 如果收到云打印指令设备故障无法执行任务时，设备故障描述，任务
排队等候。 - 如果设备打印过程中下载报文失败导致任务结束时，下载报文失败，任务
失败。 - 如果设备打印过程中设备故障，需要用户解决可恢复继续打印时，设备故障描述，任务
暂停。 - 如果设备打印过程中设备故障，不能恢复继续打印时，设备故障描述，任务
失败。 - 如果设备打印过程中报文格式不支持导致任务结束时，报文格式错误，任务
失败。 - 如果其他异常导致任务失败时，其他异常描述，任务
失败。
具体异常错误代码详见【打印错误码】。
注意
打印机任务进度上报是应用获取打印机任务执行结果的唯一数据来源，打印机务必确保每个任务的执行结果上报成功。
为了做到这一点，我们对设备有如下建议：
- 当收到执行打印任务时，将任务的信息缓存起来，实时更新打印进度。
- 当打印完成时，需要上报打印结果，每次上报如果失败，重试3次。
- 如果上报3次都失败，则间隔一段时间上报（建议5s），直到打印任务结果上报成功为止。
- 如果设备断网或者重启导致上报失败，每次联网成功后，发现还有缓存的任务信息没有上报，则继续上报任务打印结果。
- 只有打印任务结果上报成功后，才删除缓存的任务信息。
# 打印任务取消指令
打印过程中，如果用户想取消打印，应用可通过发送本指令取消正在打印的任务。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584103546,
"action": 301,
"data": {
"cmd": "server_push_task_cancel",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_task_cancel表示打印任务取消指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务ID |
设备收到请求后，应尝试取消任务。如果取消成功，应将结果通过打印任务进度上报指令上报到应用。
注意
如果设备接收到取消指令时，任务已经结束，则不能执行取消操作，直接忽略消息即可。
# 云扫描
# 功能描述
云扫描是指从应用端发起的扫描，扫描完成后，打印机将扫描图片结果实时上传到应用端，便于用户查看和管理。
云扫描的操作流程示意如下：
流程补充说明
- 扫描确认：是否可以扫描、扫描参数是否支持、进纸器是否有纸等；
- 单页扫描完成：如果是平板扫描，扫描只有一页，可以直接上报扫描完成并返回扫描图片信息；
- 云扫描取消：用户在设备上取消扫描或者发送【扫描取消指令】来取消扫描；
# 扫描执行指令
应用可通过本指令向设备发起云扫描操作。设备收到请求后应尝试启动云扫描功能。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_cloud_scan",
"payload": {
"task_id": "123",
"scan_source": "Flat",
"paper_size": "A4",
"dpi": 600,
"image_type" : "jpg",
"color": "rgb"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
其中cmd固定为server_push_cloud_scan表示扫描执行指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 扫描任务id |
| scan_source | 字符串 | Y | 扫描源：Auto-自动识别，Flat-平板，ADF-自动进纸器 |
| paper_size | 字符串 | Y | 纸张尺寸：A4 |
| dpi | 整型 | Y | 扫描dpi |
| image_type | 字符串 | Y | 图片类型，支持：jpg、png |
| color | 字符串 | Y | 颜色：rgb-全彩，black-黑白，gray-灰度 |
设备收到请求后，通过扫描进度上报指令返回扫描执行结果。
# 扫描进度上报指令
打印机准备执行云扫描任务后，可通过本指令向应用上报任务执行进度和结果。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "server_push_cloud_scan",
"payload": {
"task_id": "123",
"cloud_scan_status": "page_done",
"error_code": "",
"error_msg": "",
"error_cause": "",
"image_info":{
"image_url": "https://xxxx",
"image_type": "jpg",
"image_index": "1"
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
其中cmd固定为server_push_cloud_scan表示扫描进度上报指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| task_id | 字符串 | Y | 扫描任务id |
| cloud_scan_status | 字符串 | Y | 扫描状态：start-扫描就绪，scanning-扫描中，page_done-单页扫描完成， finish-完成，fail-失败，cancel-取消。 |
| error_code | 字符串 | N | 错误码，故障/异常必填，详细描述见下面异常情况说明 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
| image_info | json对象 | N | 图片信息：设备扫描完一张时传 |
image_info各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| image_url | 字符串 | Y | 图片网络地址，图片尺寸与page_size应保持一致 |
| image_type | 字符串 | Y | 图片类型，支持：jpg、png |
| image_index | 整型 | Y | 图片顺序从1开始，扫描完一张返回 |
关于云扫描状态上报
云扫描状态cloud_scan_status的具体说明如下：
- 设备在接收到扫描指令，扫描就绪时，返回
cloud_scan_status为start； - 设备每次扫描开始时，返回
cloud_scan_status为scanning； - 设备扫描一张完成时，先上传图片到云存储服务获取图片网络地址，返回
cloud_scan_status为page_done（如果是平板扫描 则返回finish），image_info为扫描图片信息； - 设备使用进纸器扫描1张或者多张图片完成后，进纸器无纸则代表全部完成，返回
cloud_scan_status为finish； - 设备扫描过程中出现失败导致任务终止时，返回
cloud_scan_status为fail，error_code、error_msg见异常情况说明； - 当设备扫描过程中，用户在设备或应用端主动取消扫描时，设备取消扫描，返回
cloud_scan_status为cancel；
异常情况说明
- 如果收到云扫描指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务
失败。 - 如果收到云扫描指令设备故障无法执行任务时，设备故障描述，任务
失败。 - 如果收到云扫描指令请求参数不正确无法执行任务时，请求参数错误（通用业务异常），任务
失败。 - 如果设备扫描过程中设备故障无法继续扫描时，设备故障描述，任务
失败。 - 如果设备扫描过程中设备本地存储空间不足导致图片保存失败时，设备存储空间不足，任务
失败。 - 如果设备扫描过程中文件云存储失败时，文件云存储失败，任务
失败。 - 如果其他异常导致任务失败时，其他异常描述，任务
失败。
异常错误代码请详见打印错误码。
# 扫描取消指令
扫描过程中，当用户想取消扫描时，应用会通过发送本指令取消此次扫描操作。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1502867086,
"action": 301,
"data": {
"cmd": "server_push_cloud_scan_cancel",
"payload": {
"task_id": "123"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_cloud_scan_cancel表示扫描取消指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| task_id | 字符串 | Y | 扫描任务id |
设备收到请求后，应尝试取消。如果取消成功，应将结果通过扫描进度上报指令上报到应用。
注意
如果设备接收到取消指令时，任务已经结束，则不能执行取消操作，直接忽略消息即可。
# 云清洁
# 功能描述
在用户长期使用过程中，打印机可能会出现缺失某一种色彩、文字深浅不一、图片上有明显的线条等打印问题，云清洁功能可以一定程度解决这些问题，改善打印的画质。
云清洁操作流程示意如下：
流程补充说明
- 执行确认：设备是否空闲、是否故障，请求参数是否正确；
- 清洁打印暂停：设备在打印过程中出现出现部分可恢复的故障导致打印暂停，具体故障由设备产品确定（可包含：缺纸、纸张放置不正确等）；
- 暂停后恢复打印：解决暂停故障后，设备可以恢复继续打印；
- 清洁打印失败：设备在处理清洁任务过程中，无法执行任务或者由于故障导致清洁失败，则返回清洁失败；
- 清洁打印取消：如果清洁过程中设备收到来自用户通过设备或应用发起的主动取消清洁指令时，则返回清洁取消，任务结束。
# 云清洁执行指令
应用可通过本指令向设备发起清洁操作。设备收到请求后，应启动清洁功能。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_cloud_clean",
"payload": {
"task_id": "123",
"clean_mode": "normal"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
其中cmd固定为server_push_cloud_clean表示云清洁执行指令，请求payload各参数描述如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 清洁任务id |
| clean_mode | 字符串 | N | 清洁模式，不传使用默认模式。normal-普通清洁, deep-深度清洁，可自定义配置（其他模式由产品决定） |
设备收到请求后，应通过云清洁进度上报指令上报扫描进度。
# 云清洁进度上报指令
打印机准备执行云清洁任务后，可通过本指令向应用上报任务执行进度和结果。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "server_push_cloud_clean",
"payload": {
"task_id": "123",
"clean_status": "cleaning",
"error_code": "",
"error_msg": "",
"error_cause": ""
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
其中cmd固定为server_push_cloud_clean表示云清洁进度上报指令，请求payload各参数描述如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 清洁任务id |
| clean_status | 字符串 | Y | 清洁状态：cleaning-清洁中，finish-清洁成功，pause-清洁暂停，fail-清洁失败，cancel-清洁取消 |
| error_code | 字符串 | N | 错误码，故障/异常必填，详细描述见下面异常情况说明 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
关于清洁状态上报
清洁状态clean_status的具体说明如下：
- 开始清洁时，返回
clean_status为cleaning； - 设备在清洁打印过程中出现部分原因会导致打印暂停，返回
clean_status为pause，暂停原因见异常情况说明； - 当清洁打印因故暂停，在解决故障恢复打印后，返回
clean_status为cleaning； - 清洁打印失败终止时，返回
clean_status为fail，失败原因见异常情况说明； - 当设备收到来自用户主动取消清洁的指令后，返回
clean_status为cancel； - 当清洁完成后，返回
clean_status为finish；
异常情况说明
- 如果收到云清洁指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务
失败。 - 如果收到云清洁指令设备故障无法执行任务时，设备故障描述，任务
失败。 - 如果收到云清洁指令请求参数不正确无法执行任务时，请求参数错误（通用业务异常），任务
失败。 - 如果设备清洁打印过程中设备故障，需要用户解决可恢复继续清洁打印时，设备故障描述，任务
暂停。 - 如果设备清洁打印过程中设备故障，不能恢复继续清洁打印时，设备故障描述，任务
失败。 - 如果其他异常导致任务失败时，其他异常描述，任务
失败。
异常错误代码详见打印错误码。
# 云清洁取消指令
云清洁过程中，当用户想取消设备云清洁时，可发送本指令取消此次清洁操作。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1502867086,
"action": 301,
"data": {
"cmd": "server_push_cloud_clean_cancel"
}
}
2
3
4
5
6
7
8
9
10
其中cmd固定为server_push_cloud_clean_cancel表示云清洁取消指令，无请求payload。
设备收到请求后，应尝试取消任务。如果取消成功，应将清洁结果通过云清洁进度上报指令上报到应用。
注意
如果设备接收到取消指令时，任务已经结束，则不能执行取消操作，直接忽略消息即可。
# 打印校准
# 功能描述
在用户长期使用过程中，打印机可能会出现文字、图像重影，线条不直歪斜等打印问题，校准可以改善打印的画质。
打印校准操作流程示意如下：
流程补充说明
- 执行确认：设备是否空闲、是否故障，请求参数是否正确；
- 校准打印暂停：设备在打印过程中出现出现部分可恢复的故障导致打印暂停，具体故障由设备产品确定（可包含：缺纸、纸张放置不正确等）；
- 暂停后恢复打印：解决暂停故障后，设备可以恢复继续打印；
- 校准打印失败：设备在处理校准打印任务过程中，无法执行任务或者由于故障导致校准失败，则返回校准打印失败；
- 校准打印取消：如果清洁过程中设备收到来自设备或应用端的取消校准打印指令，则返回校准打印取消。
# 校准打印执行指令
应用可通过本指令向设备发起打印校准操作。设备收到请求后，应启动打印校准功能。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_alignment_print",
"payload": {
"task_id": "123"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_alignment_print表示校准打印执行指令，payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| task_id | 字符串 | Y | 校准任务id |
设备收到请求后，应通过校准打印进度上报指令上报打印进度。
# 校准打印进度上报指令
打印机准备执行校准打印任务后，可通过本指令向应用上报任务执行进度和结果。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "server_push_alignment_print",
"payload": {
"task_id": "123",
"print_status": "printing",
"total_page_count":2,
"printed_page_count":0,
"error_code": "",
"error_msg": "",
"error_cause": ""
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
其中cmd固定为server_push_alignment_print表示校准打印进度上报指令，payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 校准任务id |
| print_status | 字符串 | Y | 校准打印状态：printing-打印中，pause-打印暂停，finish-打印成功，fail-打印失败，cancel-打印取消 |
| printed_page_count | 正整数 | Y | 已打印页数 |
| total_page_count | 正整数 | Y | 打印总页数 |
| error_code | 字符串 | N | 错误码，故障/异常必填，详细描述见下面异常情况说明 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
关于校准打印状态上报
校准打印状态print_status的具体说明如下：
- 开始打印时，返回
print_status为printing； - 设备在打印过程中出现部分原因会导致打印暂停，返回
print_status为pause，暂停原因见异常情况说明； - 当校准打印因故暂停，在解决故障恢复打印后，返回
print_status为printing； - 打印任务出现失败时，返回
print_status为fail，error_code、error_msg见异常情况说明； - 当设备收到来自设备或应用的取消校准打印指令后，返回
print_status为cancel； - 当打印完成后，返回
print_status为finish；
异常情况说明
- 如果收到校准打印指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务
失败。 - 如果收到校准打印指令设备故障无法执行任务时，设备故障描述，任务
失败。 - 如果收到校准打印指令请求参数不正确无法执行任务时，校准打印业务不支持（通用业务异常），任务
失败。 - 如果设备校准打印过程中设备故障，需要用户解决可恢复继续打印时，设备故障描述，任务
暂停。 - 如果设备校准打印过程中设备故障，不能恢复继续打印时，设备故障描述，任务
失败。 - 如果其他异常导致任务失败时，其他异常描述，任务
失败。
异常错误代码详见打印错误码。
# 校准打印取消指令
校准打印过程中，当用户想取消校准时，可发送本指令取消此次校准打印操作。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1502867086,
"action": 301,
"data": {
"cmd": "server_push_alignment_print_cancel"
}
}
2
3
4
5
6
7
8
9
10
其中cmd固定为server_push_alignment_print_cancel表示校准打印取消指令，无请求payload。
设备收到请求后，应尝试取消任务。如果取消成功，应将校准打印结果通过校准打印进度上报指令上报到应用。
注意
如果设备接收到取消指令时，任务已经结束，则不能执行取消操作，直接忽略消息即可。
# 校准参数设置指令
当设备打印完校准页后，用户可以通过打印结果对比对设备打印参数进行设置，并通过本指令下发校准后的参数结果。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1502867086,
"action": 301,
"data": {
"cmd": "server_push_alignment_set",
"payload": {
"task_id": "123",
"set_properties":[{
"key": "key1",
"value": "value1"
}]
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
其中cmd固定为server_push_alignment_set表示校准参数设置指令，payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| task_id | 字符串 | Y | 校准任务id |
| set_properties | 设置数组 | Y | 其中设置对象：key为属性名，value为属性值 |
设备收到请求后，对参数进行设置和校准，并返回校准结果。
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "server_push_alignment_set",
"payload": {
"task_id": "123",
"set_status": "success",
"error_code": "",
"error_msg": "",
"error_cause": ""
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 校准任务id |
| set_status | 字符串 | Y | 设置状态：success-成功，fail-失败 |
| error_code | 字符串 | N | 错误码，故障/异常必填，详细描述见下面异常情况说明 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
# 自动校准
# 功能描述
跟打印校准功能相同，在其基础上将校准设置由用户手动设置改为设备自动识别，提升了用户体验。
自动校准操作流程示意如下：
# 自动校准执行指令
应用可通过本指令向设备发起自动校准操作。设备收到请求后，应启动自动校准功能。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_auto_alignment",
"payload": {
"task_id": "123"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_auto_alignment表示自动校准执行指令，payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| task_id | 字符串 | Y | 自动校准任务id |
设备收到请求后，应在同一消息上下文向应用返回确认，避免应用频繁重复发送通知，并通过自动校准进度上报指令上报自动校准的进度及结果。
响应示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1584091074,
"action": 300,
"data": {
"cmd": "server_push_auto_alignment"
}
}
2
3
4
5
6
7
8
9
10
# 自动校准进度上报指令
给应用上报自动校准的进度及结果。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1502867086,
"action": 300,
"data": {
"cmd": "server_push_auto_alignment_progress",
"payload": {
"task_id": "123",
"status": "calibrating",
"error_code": "",
"error_msg": "",
"error_cause": ""
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
其中cmd固定为server_push_auto_alignment表示自动校准进度上报指令，payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 自动校准任务id |
| status | 字符串 | Y | 状态：calibrating-校准中， success-成功， failed-失败，cancelled-取消 |
| error_code | 字符串 | N | 错误码，故障/异常必填。 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填。 |
| error_cause | 字符串 | N | 错误原因，方便调查解决问题，选填。 |
关于上报自动校准进度及结果
设备在启动自动校准后，按照如下规则上报进度及结果：
- 如果收到自动校准执行指令，可以执行自动校准时，返回
status为calibrating； - 如果自动校准过程中用户主动取消校准，返回
status为cancelled； - 如果收到自动校准执行指令不能执行或者自动校准过程中校准失败时，返回
status为failed，error_code、error_msg传具体失败原因的异常错误代码； - 如果自动校准完成时，返回
status为success；
异常错误代码详见打印错误码。
应用收到请求后，应用会在同一消息上下文向设备返回确认。
响应示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1584091074,
"action": 300,
"data": {
"cmd": "server_push_auto_alignment_progress"
}
}
2
3
4
5
6
7
8
9
10
# 自动校准取消指令
自动校准过程中，用户想取消校准时，可发送此指令告知设备取消校准。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1502867086,
"action": 301,
"data": {
"cmd": "server_push_auto_alignment_cancel"
}
}
2
3
4
5
6
7
8
9
10
其中cmd固定为server_push_auto_alignment_cancel表示自动校准取消指令，无请求payload。
设备收到请求后，应在同一消息上下文向应用返回确认，如果设备正在自动校准中，并尝试取消自动校准任务。
响应示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"time": 1584091074,
"action": 300,
"data": {
"cmd": "server_push_auto_alignment_cancel"
}
}
2
3
4
5
6
7
8
9
10
注意
设备接收到取消指令时，如果任务已经结束，则不需要执行取消操作。如果任务还在进行中，则尝试取消任务，最终结果以设备实际执行结果为准。
# 云复印
# 功能描述
云复印是指从应用端发起的复印，用户在应用端设置复印参数和布局，然后通过文件扫描和打印两个步骤完成文件的个性化复印操作。
云复印的操作流程示意如下：
流程说明
- 任务执行确认：设备是否空闲、是否故障，请求参数是否正确；
- 扫描继续：应用发送【云复印继续扫描指令】可使设备继续扫描下一页。如果设备重复收到相同页的继续扫描请求可以忽略；
- 扫描完成：应用发送【云复印扫描完成指令】可使设备结束扫描进入打印阶段；
- 任务暂停：设备在复印过程中可能会因某些原因导致任务暂停，原因包含：缺纸、卡纸、打印头过热等；
- 恢复任务：解决暂停故障后，设备可以继续云复印任务；
- 任务失败：设备无法执行任务或者由于故障导致复印失败，则返回复印失败，结束整个流程；
- 复印取消：设备在云复印过程中任意阶段收到【云复印取消指令】时都应主动取消复印任务，并返回对应阶段的取消状态；
- 等待超时：云复印中需要用户操作时，需要等待用户操作并确认，超时则返回任务取消，超时时间为60s；
# 云复印执行指令
应用可通过本指令向打印机设备发起云复印操作，设备收到请求后应尝试启动云复印功能。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_cloud_copy",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d",
"preview": false,
"print_setting": {
"paper_size": "A4",
"paper_type": "plain",
"quality": "m",
"copy_type": "synthesis",
"layout_info": {
"print_direction": "vertical",
"print_layout": "2x1",
"content_layout": "to_down_to_left"
},
"print_count": 1,
"color": "rgb",
"concentration": 0
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
其中cmd固定为server_push_cloud_copy表示云复印执行指令，请求payload各参数描述如下。
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
| preview | boolean | N | 是否需要预览扫描结果。true表示是，false表示否。缺省是false |
| print_setting | json对象 | Y | 打印设置 |
print_setting各参数描述如下:
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| paper_size | 字符串 | Y | 纸张尺寸：A4。 |
| paper_type | 字符串 | N | 纸张类型:plain-普通纸(默认)，photo-相片纸，inkjet-喷墨纸 |
| quality | 字符串 | Y | 打印质量，l-低，m-中，h-高 |
| copy_type | 字符串 | N | 复印类型，synthesis-多合一复印，zoom-缩放复印(默认) |
| zoom | 浮点数 | N | 缩放比例：1.00(默认)，保留2位小数。仅缩放复印生效 |
| layout_info | json对象 | N | 布局类型，仅多合一复印生效 |
| print_count | 整型 | Y | 打印次数 |
| color | 字符串 | Y | 颜色：rgb-彩色，black-黑白 |
| concentration | 整型 | N | 复印浓度: -2，-1，0(默认)，1，2 |
layout_info各参数描述如下:
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| print_direction | 字符串 | Y | 打印纸张方向，vertical-纵向，horizontal-横向 |
| print_layout | 字符串 | Y | 打印布局，1x2(1列2行)，2x1(2列1行)，2x2(2行2列) |
| content_layout | 字符串 | N | 内容排布顺序， to_right_to_down-从左上角开始按行排列，向右和向下排列； to_down_to_right-从左上角开始按列排列，向下和向右排列； to_up_to_right-从左下角开始按列排列，向上和向右排列； to_up_to_left-从右下角开始按列排列，向上和左排列； to_right_to_up-从左下角开始按行排列，向右和向上排列； to_down_to_left-从右上角开始按列排列，向下和向左排列； to_left_to_up-从右下角开始按行排列，向左和向上排列； to_left_to_down-从右上角开始按行排列，向左和向下排列。 |
| duplicate_content | boolean | N | 是否重复复印，true-重复，false-不重复(默认) |
content_layout字段表示的内容排布示意图：
| 参数 | 说明 | 示意图 |
|---|---|---|
| to_right_to_down | 从左上角开始按行排列，向右和向下排列 |  |
| to_down_to_right | 从左上角开始按列排列，向下和向右排列 |  |
| to_up_to_right | 从左下角开始按列排列，向上和向右排列 |  |
| to_up_to_left | 从右下角开始按列排列，向上和左排列 |  |
| to_right_to_up | 从左下角开始按行排列，向右和向上排列 |  |
| to_down_to_left | 从右上角开始按列排列，向下和向左排列 |  |
| to_left_to_up | 从右下角开始按行排列，向左和向上排列 |  |
| to_left_to_down | 从右上角开始按行排列，向左和向下排列 |  |
注意
- layout_info 参数仅在多合一复印时生效；
- zoom 参数仅在缩放复印时生效；
- content_layout、duplicate_content 两者传其一，若都传，duplicate_content优先级高于content_layout；
设备收到请求后，通过【云复印进度上报指令】返回云复印执行结果。
# 云复印进度上报指令
打印机在执行云复印任务时，通过本指令向应用上报任务执行进度和结果。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"action": 300,
"time": 1584091154,
"data": {
"cmd": "printer_push_cloud_copy_progress",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d",
"cloud_copy_step": "scan",
"cloud_copy_status": "executing",
"scanned_page_count": 2,
"printed_page_count": 0,
"error_code": "",
"error_msg": "",
"error_cause": "",
"preview_info":{
"image_url": "http://xxxx",
"image_type": "jpg"
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
其中cmd固定为printer_push_cloud_copy_progress表示云复印进度上报指令，响应payload各参数说明如下：
| 参数 | 类型 | 是否必传 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务ID |
| cloud_copy_step | 字符串 | Y | 任务阶段：scan-扫描阶段，print-打印阶段 |
| cloud_copy_status | 字符串 | N | 任务状态：executing-执行中，finish-成功，fail-失败，cancel-取消，pause-暂停 |
| scanned_page_count | 整型 | Y | 已扫描页数，累计 |
| printed_page_count | 整型 | Y | 已打印页数，累计 |
| preview_info | json对象 | N | 预览图片信息，仅需要预览扫描结果时返回 |
| error_code | 字符串 | N | 错误码，故障/异常必填 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
preview_info各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| image_url | 字符串 | Y | 图片网络地址，图片尺寸与page_size应保持一致 |
| image_type | 字符串 | Y | 图片类型，支持：jpg、png |
关于云复印状态上报
- 设备在接收到【云复印执行指令】并进入扫描状态时，返回
cloud_copy_step为scan，cloud_copy_status为executing； - 设备扫描完一张复印原件时，返回
cloud_copy_step为scan，cloud_copy_status为executing，更新scanned_page_count(如果需要预览时同步返回preview_info)； - 设备扫描完成时，返回
cloud_copy_step为scan，cloud_copy_status为finish，更新scanned_page_count； - 设备扫描完成并进入打印状态时，返回
cloud_copy_step为print，cloud_copy_status为executing； - 设备在完成一页打印时，返回
cloud_copy_step为print，cloud_copy_status为executing，更新printed_page_count； - 设备打印完最后一张时，返回
cloud_copy_step为print，cloud_copy_status为finish，更新printed_page_count； - 设备任意阶段因某些原因导致任务暂停时，返回
cloud_copy_status为pause，恢复任务后返回cloud_copy_status为executing； - 设备任意阶段因某些原因导致任务取消时（例如设备端主动取消或收到【云复印取消指令】），设备取消任务并返回
cloud_copy_status为cancel； - 设备任意阶段因设备故障导致任务失败时，返回
cloud_copy_status为fail，error_msg见异常情况说明；
异常情况说明
- 如果收到云复印指令设备正忙，设备忙（通用业务异常），任务
失败。 - 如果收到云复印指令参数不支持或者无效，请求参数错误（通用业务异常），任务
失败。 - 如果设备在执行过程中设备故障，可恢复时，设备故障描述，任务
暂停。 - 如果设备在执行过程中设备故障，不能恢复时，设备故障描述，任务
失败。 - 如果设备复印等待用户确认时，等待超时，设备故障描述，任务
取消。 - 如果其他异常导致任务失败时，其他异常描述，任务
失败。
具体异常错误代码详见【打印错误码】。
# 云复印取消指令
云复印执行过程中用户可通过应用发送本指令向打印机设备请求取消此次复印。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1502867086,
"action": 301,
"data": {
"cmd": "server_push_cloud_copy_cancel",
"payload": {
"task_id": "123"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_cloud_copy_cancel表示云复印取消指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
设备收到请求后，应尝试取消。如果取消成功，应将云复印结果通过云复印进度上报指令上报到应用。
注意
如果设备接收到取消指令时，任务已经结束，则不能执行取消操作，直接忽略消息即可。
# 云复印继续扫描指令
当设备完成一次扫描之后会暂停等待用户确认是否需要继续扫描，用户完成复印原件放置后通过应用发送本指令可以继续云复印扫描。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_cloud_copy_scan_continue",
"payload": {
"task_id": "123",
"scanned_page_count": 1
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
其中cmd固定为server_push_cloud_copy_scan_continue表示云复印继续扫描指令，payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
| scanned_page_count | 整型 | Y | 已扫描页数。设备应通过本字段判断是否收到重复的扫描请求，避免相同的文件扫描多次 |
设备收到请求后应继续扫描，扫描结果应通过云复印进度上报指令上报到应用。
# 云复印扫描完成指令
当云复印的所有文件全部扫描完成后，应用应通过本指令通知设备结束扫描并启动打印。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_cloud_copy_scan_complete",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_cloud_copy_scan_complete表示云复印扫描完成指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
设备收到请求后的状态更新结果应通过云复印进度上报指令上报到应用。
# 证件复印
# 功能描述
证件复印和云复印类似，都是从应用端发起。但证件复印主要是用于正反面复印证件，因此设备每次扫描时仅扫描一半的区域，并最终通过合成两次扫描的结果输出最终复印件。
证件复印的操作流程与云复印基本一致，如下所示：
# 证件复印执行指令
应用可通过本指令向打印机设备发起证件复印操作，设备收到请求后应尝试启动证件复印功能。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_credential_copy",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d",
"preview": false,
"print_setting": {
"paper_size": "A4",
"paper_type": "plain",
"quality": "m",
"print_count": 1,
"color": "black",
"concentration": 0
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
其中cmd固定为server_push_credential_copy表示证件复印执行指令，请求payload各参数描述如下。
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
| preview | boolean | N | 是否需要预览扫描结果。true表示是，false表示否。缺省是false |
| print_setting | json对象 | Y | 打印设置 |
print_setting各参数描述如下:
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| paper_size | 字符串 | Y | 纸张尺寸：A4。 |
| paper_type | 字符串 | Y | 纸张类型:plain-普通纸，photo-相片纸，inkjet-喷墨纸 |
| quality | 字符串 | Y | 打印质量，l-低，m-中，h-高 |
| print_count | 整型 | Y | 打印次数，1~99 |
| color | 字符串 | Y | 颜色：rgb-彩色，black-黑白 |
| concentration | 整型 | Y | 复印浓度: -2，-1，0，1，2 |
设备收到请求后，通过证件复印进度上报指令返回证件复印执行结果。
# 证件复印进度上报指令
打印机执行证件复印任务时，可通过本指令向应用上报任务执行进度和结果。
请求示例如下：
{
"mid": "123456",
"from": "M2500ADNW_12345678",
"to": "511542236802977792",
"action": 300,
"time": 1584091154,
"data": {
"cmd": "printer_push_credential_copy_progress",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d",
"credential_copy_step": "scan",
"credential_copy_status": "executing",
"scanned_page_count": 2,
"printed_page_count": 0,
"error_code": "",
"error_msg": "",
"error_cause": "",
"preview_info":{
"image_url": "https://xxxx",
"image_type": "jpg"
}
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
其中cmd固定为printer_push_credential_copy_progress表示证件复印进度上报指令，响应payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
| credential_copy_step | 字符串 | Y | 任务状态：scan-扫描阶段，print-打印阶段 |
| credential_copy_status | 字符串 | Y | 任务阶段：executing-执行中，finish-成功，fail-失败，cancel-取消，pause-暂停 |
| preview_info | json对象 | N | 预览图片信息，仅需要预览扫描结果时返回 |
| scanned_page_count | 整型 | Y | 已扫描页数，累计 |
| printed_page_count | 整型 | Y | 已打印页数，累计 |
| error_code | 字符串 | N | 错误码，故障/异常必填 |
| error_msg | 字符串 | N | 错误描述，故障/异常必填 |
| error_cause | 字符串 | N | 错误原因，选填。方便调查解决问题 |
preview_info各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| image_url | 字符串 | Y | 图片网络地址 |
| image_type | 字符串 | Y | 图片类型，支持：jpg、png |
证件复印状态上报逻辑与云复印状态上报基本一致，这里不再重复阐述。
# 证件复印取消指令
证件复印过程中用户可通过应用发送本指令取消此次证件复印。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_credential_copy_cancel",
"payload": {
"task_id": "123"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_credential_copy_cancel表示证件复印取消指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
设备收到请求后，应尝试取消。如果取消成功，应将证件复印结果通过证件复印进度上报指令上报到应用。
注意
如果设备接收到取消指令时，任务已经结束，则不能执行取消操作，直接忽略消息即可。
# 证件复印继续扫描指令
当设备完成证件正面扫描后会暂停等待用户放置证件反面，用户完成放置后通过应用发起本指令继续证件扫描。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_credential_copy_scan_continue",
"payload": {
"task_id": "123"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_credential_copy_scan_continue表示证件复印继续扫描指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
设备收到请求后应继续扫描，扫描结果应通过证件复印进度上报指令上报到应用。
# 证件复印扫描完成指令
当证件的正反面都扫描完成后，应用应通过本指令通知设备结束扫描并启动打印。
请求示例如下：
{
"mid": "123456",
"from": "511542236802977792",
"to": "M2500ADNW_12345678",
"time": 1584091074,
"action": 301,
"data": {
"cmd": "server_push_credential_copy_scan_complete",
"payload": {
"task_id": "Pf642ad1468eb4482998e61001b0b560d"
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
其中cmd固定为server_push_credential_copy_scan_complete表示证件复印扫描完成指令，请求payload各参数说明如下：
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| task_id | 字符串 | Y | 任务id |
设备收到请求后的状态更新结果应通过证件复印进度上报指令上报到应用。
# 固件升级
请根据设备平台指令集中设备固件升级来实现固件升级功能，考虑到打印机固件升级存在较大风险，建议采用手动升级模式。
# 打印错误码
本章节主要定义导致设备功能不可用以及业务执行暂停或者异常结束的错误码定义，错误码主要包含：设备故障错误码和业务异常错误码。
分别说明如下：
# 设备故障错误码
设备故障错误码是指设备硬件本身发生故障，会导致部分功能不可使用的故障错误信息。例如：进纸托盘处无纸、纸张放置不正确、墨盒仓门已打开、进纸托盘处发生卡纸等。
由于不同设备厂商，不同设备型号的故障类型有很多不同，设备故障错误码有厂商自行定义。
如果设备发生故障时:
设备故障码要求：
- 设备故障错误码为4～5位的整数，便于区分业务异常和设备故障。
- 设备故障错误描述将直接提示给用户，请产品做好文字描述。
# 业务异常错误码
业务异常错误码主要是指设备执行业务任务过程中，出现导致任务暂停或者异常结束的业务异常错误信息（非设备硬件本身的故障）。
例如：设备忙（执行A任务不能执行B任务）、请求参数异常（业务请求参数不合法或者不支持）等。
如果设备执行业务任务过程中出现业务异常导致任务暂停或者任务异常结束，需要上报任务执行状态以及业务错误码信息，上报指令根据业务类型选择，例如：打印任务进度上报指令、扫描进度上报指令 等。
目前定义的业务异常错误码有：
| 业务类型 | 错误码 | 错误描述 | 错误原因 | 错误原因说明 |
|---|---|---|---|---|
| 通用 | 100001 | 设备忙 | --- | 收到新任务请求，因为设备正在其他任务而不能执行当前任务 |
| 通用 | 100002 | 不支持xxx（具体错误描述由产品定义） | 不支持的参数："param1、param2"。（param1、param2为参数属性名） | 由于固件版本或者产品配置不正确，导致业务请求参数不支持。错误描述比如："不支持自动进纸器扫描"，"不支持A4纸张尺寸"等 |
| 通用 | 100003 | 设备存储空间不足 | --- | 由于设备存储空间不足，导致有文件存储的业务任务失败 |
| 通用 | 100004 | 文件云存储失败 | --- | 设备将本地文件上传云端保存失败 |
| 通用 | 100999 | 未知异常描述（详细错误描述由产品定义） | 导致异常的具体原因，方便后期调查 | 当处理业务过程中，出现本文档未定义的异常上报，注意 具体描述由产品定义 |
| 云打印 | 201001 | 文件下载失败 | httpStatus信息 | 开始执行任务后，打印机从云端下载报文失败 |
| 云打印 | 201002 | 文件格式不支持 | --- | 打印机下载的报文格式错误或者报文参数不支持 |
关于异常错误码
- 错误码
error_code：错误的唯一标识，方便后期统计、查询、解决错误。 - 错误描述
error_msg：业务处理过程中出现了异常，提示给用户当前发生了什么。给用户的提示，提示需要产品定义 - 错误原因
error_cause：错误发生的具体原因，方便研发定位解决问题。
# 变更记录
| 变更时间 | 协议版本 | 变更人 | 变更内容 |
|---|---|---|---|
| 2020/07/11 | v1.0 | 徐超国 | 整理并发布云打印接入协议初版 |
| 2020/08/20 | v1.1 | 胡金喜 | 新增 1、云扫描 2、 3、固件升级 4、增加接入指南 修改： 1、 优化协议描述 |
| 2021/06/02 | v1.2 | 胡金喜 | 新增 1、云清洁 2、打印校准 修改： 1、针对业务错误码进行了优化，分为设备故障错误码以及业务异常错误码，错误信息分为： error_code为错误标识，error_msg为错误描述，提示给用户，error_cause为错误原因，方便调查解决问题。影响指令/功能：设备信息同步、云打印、云扫描、证件扫描、固件升级 2、新增打印任务进度上报指令的打印状态 print_status:queue-排队等待、pause-暂停3、设备信息上报指令：修改了墨盒/硒鼓的状态描述 删除： 1、设备错误信息上报指令，应用已不再处理此指令 |
| 2021/08/01 | v1.2 | 徐超国 | 按照设备功能重新进行了文档编排，协议内容无变更 |
| 2021/08/06 | v1.3 | 胡金喜 | 新增 1、打印机网络信号强度的上报。设备信息上报指令 增加属性： wifi_rssi |
| 2021/09/09 | v1.4 | 秦嘉威 | 新增 1、云复印 2、证件复印 |
| 2022/03/19 | v1.5 | 胡金喜 | 新增 1、增加打印头信息上报：新打印头需要初始化校准才能使用。更新指令设备信息同步 |