云打印接入协议1.2

云打印接入协议主要描述了云打印场景下设备设备与云打印应用如何通过数据交互实现设备信息上报、打印任务下发执行等云打印关键业务。

时间 版本 修订人 修订说明
2020-07-11 1.0 徐超国 整理并发布打印接入协议初版
2020-08-20 1.1(history/cloudprint1.1) 胡金喜 新增
  1、云扫描功能
  2、证件扫描功能
  3、固件升级功能
  4、增加接入指南
修改
  1、 优化协议描述
2021-06-02 1.2 胡金喜 新增
  1、云清洁功能
  2、打印校准功能
修改
  1、针对业务错误码进行了优化,分为设备故障错误码以及业务异常错误码,错误信息分为:error_code为错误标识,error_msg为错误描述,提示给用户,error_cause为错误原因,方便调查解决问题。
涉及指令/功能:设备信息上报指令云打印云扫描功能证件扫描功能固件升级功能
  2、云打印功能新增打印状态:排队等待、暂停
  3、设备信息上报:修改了墨盒/硒鼓的状态描述
删除
  1、设备错误信息上报指令,应用已不再处理此指令

云打印设备接入指南

连接平台接入介绍

设备接入平台有详细介绍,请仔细阅读得力E+开放文档中心.

特别注意

平台指令接入介绍

平台是设备与应用的通讯桥梁,设备与应用所有交互通讯通过平台中转完成,下面表格只介绍跟云打印相关的指令,更多平台指令介绍详情请阅读平台标准指令集)。

指令 接入说明 其他说明
平台1xx指令-100 必须接入 保证时间同步
平台1xx指令-101 必须接入 e+设备信息来源。
影响功能:固件升级、设备状态显示。
平台1xx指令-102 必须接入 获取设备信息、绑定应用、绑定组织,是否有新固件等信息。
配合平台指令-203平台指令-204使用,
云打印很多功能需要设备被绑定才能使用,建议连接平台时以及定时发送102指令进行信息同步
平台1xx指令-103 可接入 固件升级功能,产品需求决定是否接入
平台1xx指令-104 可接入 设备主动解绑功能,产品需求决定是否接入
平台1xx指令-105 可接入 设备告警用,当设备出现未知异常时上报触发警报
平台2xx指令-203 必须接入 设备被绑定组织时通知设备
平台2xx指令-204 必须接入 设备被绑定应用时通知设备
平台2xx指令-206 可接入 手动固件升级功能,产品需求决定是否接入
平台3xx指令-300 必须接入 设备发送业务指令
平台3xx指令-301 必须接入 设备接收业务指令。
注意如果收到不支持的指令,必须响应cmd_not_support

应用指令接入介绍

指令 接入说明 其他说明
设备信息同步 必须接入 应用获取设备信息来源
云打印 必须接入 基础打印功能。
要求设备绑定组织
云扫描 可接入 云扫描功能,产品需求决定是否接入。
要求设备绑定组织
证件扫描 可接入 证件扫描功能,产品需求决定是否接入。
要求设备绑定组织
固件升级 可接入 手动固件升级功能,产品需求决定是否接入。
要求设备绑定组织
云清洁 可接入 云清洁功能,产品需求决定是否接入。
要求设备绑定组织
打印校准 可接入 打印校准功能,产品需求决定是否接入。
要求设备绑定组织

设备信息同步

设备信息上报

设备主动上报设备当前信息,以便云打印应用掌握设备最新信息,包含:网络信息、固件版本、墨盒信息、设备故障状态信息等。

以下情况设备都应主动使用本指令向应用上报设备最新信息:

请求示例:

{
    "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",
            "mac_address": "EC:F0:0E:84:36:FE",
            "ssid": "DELI",
            "network_mode": "WLAN",
            "printer_ip": "172.193.12.11",
            "total_page_count": "10",
            "total_paper_count": "7",
            "error_paper_count": "0",
            "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"
                }]
            }]
        }
    }
}

其中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-蓝牙
ssid 字符串 N 如果WLAN连接,WIFI的ssid
printer_ip 字符串 N ip地址
mac_address 字符串 N mac地址
total_page_count 字符串 Y 设备总打印面数,累计
total_paper_count 字符串 Y 打印纸张数,累计
error_paper_count 字符串 Y 打印错误纸张数:卡纸等。累计
inkboxs inkbox列表 Y inkbox是墨盒对象(碳粉盒 or 墨水盒)
表示一个更换的整体

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种

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

设备信息查询

应用可通过本指令主动向设备设备获取设备最新信息,设备收到查询请求后,通过应用指令-设备信息上报指令上报最新的设备信息。

请求示例:

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584103546,
    "action": 301,
    "data": {
        "cmd": "server_push_report_info"
    }
}

其中cmd固定为server_push_report_info表示设备信息查询,无payload信息。

响应示例:

{
    "mid": "123456",
    "from": "M2500ADNW_12345678", 
    "to": "511542236802977792", 
    "time": 1555307488,
    "action": 300,
    "data": {
        "cmd": "server_push_report_info"
    }
}

云打印

功能流程图:


participant 用户 as user
participant 应用 as app
participant 设备 as device

user->app: 1、选择文件打印
app->app: 2、打印报文转换
app->device: 3、发送[打印任务通知]指令
device->app: 4、发送[打印任务执行]指令
app--device: 5、返回执行任务详情
Note left of device: 如果设备繁忙或者故障不能执行任务
device--app: 返回任务打印结果:排队等待中
device--device: 6、开始打印
device->app: 7、返回任务进度:打印中
device--device: 8、打印完成一页
device->app: 9、返回任务进度:打印中,已打印页数

Note left of device: 如果设备出现故障打印被暂停
device--app: 返回任务状态:打印暂停
Note left of device: 解决故障,恢复打印
device--app: 返回任务状态:打印中

Note left of device: 如果打印取消
device--app: 返回任务打印结果:打印取消

Note left of device: 如果打印失败
device--app: 返回任务打印结果:打印失败

device--device: 10、打印完成。
device->app: 11、返回任务打印结果:打印完成

app->user: 12、给用户返回打印结果

流程说明:

打印任务通知

当设备有新的打印任务时,云打印应用服务会通过本指令向设备下发任务通知。

请求示例:

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_task_add",
        "payload": {
            "task_type": "print"
        }
    }
}

其中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",
    }
}

响应无payload信息。

注意

打印任务执行

当设备可通过此指令,获取当前设备可执行任务信息,下载打印报文打印。

以下情况执行此指令:

请求示例:

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086,
    "action": 300,
    "data": {
        "cmd": "printer_push_task_execute"
    }
}

其中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"
            }
        }
    }
}

响应payload参数说明如下:

参数 类型 是否必填 说明
task_status 字符串 Y 是否有可执行任务:0-没有任务,1-有任务
task_id 字符串 N 任务ID。有任务时返回
task_type 字符串 N 任务类型:print-打印。有任务时返回
task_info json对象 N 任务详情:不同任务类型,对象内容不同。有任务时返回

{
    "download_url": "https://domain/123"
}
其中,各参数说明如下:

参数 类型 是否必填 说明
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"
        }
    }
}

其中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的具体说明如下:

  1. 准备打印任务时,设备繁忙或者设备故障导致无法不能打印,返回print_statusqueueerror_codeerror_msg异常情况说明
  2. 设备开始打印时,返回print_statusprinting
  3. 打印过程中,每打印完一页时,返回print_statusprintingprinted_page_count已打印页数printed_paper_count已打印纸张数
  4. 打印过程中,设备出现用户解决后可恢复打印的故障,返回print_statuspauseprinted_page_count已打印页数printed_paper_count已打印纸张数,error_codeerror_msg异常情况说明
  5. 打印任务全部完成时,返回print_statusfinishprinted_page_count已打印页数printed_paper_count已打印纸张数
  6. 打印任务出现失败终止时,返回print_statusfailprinted_page_count已打印页数printed_paper_count已打印纸张数,error_codeerror_msg异常情况说明
  7. 打印任务中,取消打印或者收到指令-取消打印任务时,返回print_statuscancelprinted_page_count已打印页数printed_paper_count已打印纸张数

注意:

异常情况说明 如下:

  1. 如果收到云打印指令设备正忙(执行其他任务)无法执行任务时,设备忙(通用业务异常),任务排队等候
  2. 如果收到云打印指令设备故障无法执行任务时,设备故障描述,任务排队等候
  3. 如果设备打印过程中下载报文失败导致任务结束时,下载报文失败,任务失败
  4. 如果设备打印过程中设备故障,需要用户解决可恢复继续打印时,设备故障描述,任务暂停
  5. 如果设备打印过程中设备故障,不能恢复继续打印时,设备故障描述,任务失败
  6. 如果设备打印过程中报文格式不支持导致任务结束时,报文格式错误,任务失败
  7. 如果其他异常导致任务失败时,其他异常描述,任务失败

异常错误码请详见错误码说明

注意,应用获取打印任务结果的唯一来源是通过设备结果上报,必须保证每一个任务的执行结果必须上报成功

由于设备执行任务后,可能会因为断网、断电、网络信号弱等各种原因导致任务结果无法上报服务器,使用户无法得到任务的真实状态。 建议:

响应示例:

取消打印任务

当打印过程中,用户想取消打印,可通过应用发送本指令取消正在打印的任务。

请求示例:

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584103546,
    "action": 301,
    "data": {
        "cmd": "server_push_task_cancel",
        "payload": {
            "task_id": "Pf642ad1468eb4482998e61001b0b560d"
        }
    }
}

其中cmd固定为server_push_task_cancel表示打印任务取消,请求payload各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 任务ID

注意 设备收到请求后,如果任务未执行完毕,则应执行取消操作,并通过打印任务进度上报上报任务状态,如果任务已完成,则忽略该请求即可。

响应示例:

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1584103546,
    "action": 300,
    "data": {
        "cmd": "server_push_task_cancel"
    }
}

响应无payload信息

云扫描

功能流程图:

participant 用户 as user
participant 应用 as app
participant 设备 as device
participant 云存储服务 as css

user->app: 1、使用云扫描
app->device: 2、发送[云扫描]指令
device--device: 3、扫描确认
device->app: 4、上报扫描就绪

device--device: 5、扫描开始
device->app: 6、上报扫描中
device--device: 7、扫描结束
device->css: 8、扫描图片上传
css--device: 9、返回图片访问URL
device->app: 10、上报单页扫描完成

Note left of device:如果是平板扫描
device--app: 上报扫描完成

Note right of device:如果是自动进纸器扫描
device--device: 11、多页扫描,重复5~10

Note left of device:如果用户取消扫描
device--app: 上报扫描已取消,扫描结束

Note left of device:如果扫描失败
device--app: 上报扫描失败,扫描结束

device--device: 12、扫描完成
device->app: 13、上报扫描完成

app->user: 14、给用户返回扫描结果

流程说明:

执行云扫描

应用可通过以下指令向设备设备发起云扫描操作,设备将扫描得到的图片上传到云存储后,将图片信息返回给应用保存,完成云扫描功能。

请求示例:

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

其中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-灰度

注意: 纸张尺寸、扫描dpi、图片类型,颜色支持需要提前确认,避免不支持导致新问题。

响应示例:

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

响应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 图片网络地址
image_type 字符串 Y 图片类型,支持:jpg、png
image_index 整型 Y 图片顺序从1开始,扫描完一张返回

设备扫描状态cloud_scan_status的具体说明如下:

  1. 设备在接收到扫描指令,扫描就绪时,返回cloud_scan_statusstart
  2. 设备每次扫描开始时,返回cloud_scan_statusscanning
  3. 设备扫描一张完成时,先上传图片到云存储服务获取图片网络地址,返回cloud_scan_statuspage_done(如果是平板扫描 则返回finish),image_info扫描图片信息
  4. 设备使用进纸器扫描1张或者多张图片完成后,进纸器无纸则代表全部完成,返回cloud_scan_statusfinish
  5. 设备扫描过程中出现失败导致任务终止时,返回cloud_scan_statusfailerror_codeerror_msg异常情况说明
  6. 当设备扫描过程中,用户在设备上取消扫描或者收到指令-取消云扫描指令时,设备取消扫描,返回cloud_scan_statuscancel

异常情况说明 如下:

  1. 如果收到云扫描指令设备正忙(执行其他任务)无法执行任务时,设备忙(通用业务异常),任务失败
  2. 如果收到云扫描指令设备故障无法执行任务时,设备故障描述,任务失败
  3. 如果收到云扫描指令请求参数不正确无法执行任务时,请求参数错误(通用业务异常),任务失败
  4. 如果设备扫描过程中设备故障无法继续扫描时,设备故障描述,任务失败
  5. 如果设备扫描过程中设备本地存储空间不足导致图片保存失败时,设备存储空间不足,任务失败
  6. 如果设备扫描过程中文件云存储失败时,文件云存储失败,任务失败
  7. 如果其他异常导致任务失败时,其他异常描述,任务失败

异常错误码请详见错误码说明

取消云扫描

当用户想取消扫描时,可通过应用发送取消云扫描指令,取消此次扫描操作。

请求示例:

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_cloud_scan_cancel",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_cloud_scan_cancel表示云扫描取消指令,请求payload各参数说明如下:

参数 类型 是否必填 描述
task_id 字符串 Y 扫描任务id

注意:当设备此时正在扫描中则取消本次扫描并上报结果,没有扫描则忽略此指令

响应示例:

证件扫描

功能流程图:

participant 用户 as user
participant 应用 as app
participant 设备 as device
participant 云存储服务 as css

user->app: 1、使用证件扫描
app->device: 2、发送[证件扫描]指令
device--device: 3、扫描确认 
device->app: 4、上报证件扫描就绪

device--device: 5、扫描开始
device->app: 6、上报扫描中
device--device: 7、扫描结束
device->css: 8、扫描图片上传
css--device: 9、返回图片访问URL
device->app: 10、上报单页扫描完成

device--device: 11、等待用户确认是否继续扫描
Note left of device:如果用户取消扫描
device--app: 上报扫描取消,扫描结束

Note right of device:如果用户选择继续扫描
device--device: 12、继续扫描,重复5~11


Note left of device:如果扫描失败
device--app: 上报扫描失败,扫描结束

device--device: 13、扫描完成
device->app: 14、上报扫描完成

app->user: 15、给用户返回证件扫描结果

流程说明:

执行证件扫描

应用可通过证件指令向设备设备发起证件扫描操作,设备将多次扫描到的图像合并在一张图片上,并将得到的图片上传到云存储后,最后将图片信息返回给应用保存,完成证件扫描功能。

请求示例:

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_credential_scan",
        "payload": {
            "task_id":"123",
            "paper_size": "A4",
            "dpi": 600,
            "image_type" : "jpg",
            "color": "rgb"
        }
    }
}

其中cmd固定为server_push_credential_scan表示执行证件扫描请求, 请求payload各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 扫描任务id
paper_size 字符串 Y 纸张尺寸:A4
dpi 整型 Y 扫描dpi
image_type 字符串 Y 图片类型,支持:jpg、png
color 字符串 Y 颜色:rgb-全彩,black-黑白,gray-灰度。

注意: 纸张尺寸、扫描dpi、图片类型,颜色支持需要提前确认,避免不支持导致新问题。

响应示例:

{
    "mid": "123456", 
    "from": "M2500ADNW_12345678", 
    "to": "511542236802977792", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "server_push_credential_scan", 
        "payload": {
            "task_id":"123",
            "credential_scan_status": "page_done",
            "error_code": "",
            "error_msg": "",
            "error_cause": "",
            "image_info":{
                "image_url": "https://xxxx",
                "image_type": "jpg",
                "image_index": "1"
            }
        }
    }
}

响应payload各参数说明如下:

参数 类型 是否必填 描述
task_id 字符串 Y 扫描任务id
credential_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 图片网络地址
image_type 字符串 Y 图片类型,支持:jpg、png
image_index 整型 Y 图片顺序从1开始,扫描完一张返回

设备扫描状态credential_scan_status的具体说明如下:

  1. 设备在接收到扫描指令,开始扫描时,返回credential_scan_statusstart
  2. 设备每次扫描开始时,返回credential_scan_statusscanning
  3. 设备扫描一张完成时,先上传图片到云存储服务获取图片网络地址,然后返回credential_scan_statuspage_done(如果是平板扫描 则返回finish),image_info扫描图片信息
  4. 当设备等待状态,用户在设备上继续扫描或者收到继续证件扫描指令时,继续扫描,扫描开始时,返回credential_scan_statusscanning
  5. 设备扫描过程中出现失败导致任务终止时,返回cloud_scan_statusfailerror_codeerror_msg异常情况说明
  6. 当设备等待状态,用户在设备完成扫描 或者 等待用户继续扫描超过60s 或者 收到完成证件扫描指令时,设备结束扫描,返回credential_scan_statusfinish
  7. 如果设备扫描过程中,用户在设备上取消扫描或者收到取消证件扫描指令时,设备取消扫描,返回credential_scan_statuscancel

异常情况说明 如下:

  1. 如果收到证件扫描指令设备正忙(执行其他任务)无法执行任务时,设备忙(通用业务异常),任务失败
  2. 如果收到证件扫描指令设备故障无法执行任务时,设备故障描述,任务失败
  3. 如果收到证件扫描指令请求参数不正确无法执行任务时,请求参数错误(通用业务异常),任务失败
  4. 如果设备扫描过程中设备故障无法继续扫描时,设备故障描述,任务失败
  5. 如果设备扫描过程中本地存储空间不足导致图片保存失败时,设备存储空间不足,任务失败
  6. 如果设备扫描过程中文件云存储失败时,文件云存储失败,任务失败
  7. 如果设备扫描过程中其他异常,导致任务结束时,任务失败

异常错误码请详见错误码说明

取消证件扫描

当用户不想扫描时,可通过应用发送取消云扫描指令,取消此次扫描操作。

请求示例:

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_credential_scan_cancel",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_credential_scan_cancel表示证件扫描取消指令,请求payload各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 扫描任务id

注意:当设备此时正在证件扫描中则取消本次扫描并上报结果,没有扫描则忽略此指令。

响应示例:

继续证件扫描

当用户扫描完一次证件想继续添加扫描,在设备上放好证件后,可以在app上操作继续扫描,发送继续证件扫描指令,设备执行继续扫描。

请求示例:

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301, 
    "data": {
        "cmd": "server_push_credential_scan_continue",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_credential_scan_continue表示继续证件扫描指令,请求payload各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 扫描任务id

当设备收到此指令时,如果设备处于证件等待中,则继续证件扫描。

响应示例:

完成证件扫描

当用户扫描完一次证件想结束扫描,可以在app上操作完成,发送完成证件扫描指令,设备收到指令后结束扫描并返回扫描完成。

请求示例:

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_credential_scan_finish",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_credential_scan_finish表示完成证件扫描指令,请求payload各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 扫描任务id

注意:当设备此时正在证件扫描则完成本次扫描并上报结果,没有证件扫描则忽略此指令。

响应示例:

固件升级

固件升级有两种方式:自动升级、手机升级,详情请仔细阅读平台指令-103

注意:由于设备固件升级失败风险较大,要求用户必须知晓风险并确认才能升级,因此建议手动固件升级,下面详细介绍手动固件升级流程。

手动固件升级

手动固件升级流程图:


participant 用户 as user
participant 应用 as app
participant 设备 as device
participant 平台 as platform


user->app: 1、手动发起设备升级
app->device: 2、发送[206指令]通知设备升级
device->platform: 3、发送[103指令]获取固件信息
platform--device: 4、返回设备最新固件版本
Note right of device: 可提前获取固件信息
device->platform: 5、108指令上报升级状态:准备就绪
platform->app: 6、固件升级准备就绪
app->user: 7、准备就绪,确认是否升级

device--device: 8、等待用户确认是否升级

Note right of device:如果等待超时或者用户取消升级
device--platform: 108指令上报升级状态:升级取消


Note right of device:如果用户确认升级
device--device: 9、确认升级后,下载固件 
device->platform: 10、108指令上报下载进度

device--device: 11、安装固件
device->platform: 12、108指令上报安装进度

device--device: 13、设备重启
device->platform: 14、重启后,101指令上报升级后固件版本

platform->app: 15、固件已升级到新版本,升级完成
app-->user: 16、升级结果

流程说明:

云打印的108指令要求如下:

请求示例:

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "system",
    "time": 1555307375,
    "action": 108,
    "data": {
        "version":"1.1.0",
        "step": 0,
        "status": 0,
        "progress": 80,
        "error": ""
    }
}

指令参数描述如下:

请求参数 类型 是否必填 参数说明
version 字符串 Y 当前设备升级的版本号
step 整型 Y 升级阶段:0-准备阶段,1-下载固件阶段,2-安装固件阶段
status 整型 Y 升级状态:0-执行中,1-执行成功,2-执行失败,3-取消
progress 整型 N 升级进度[0~100]。对于支持进度显示的设备,可在升级过程中返回升级进度百分值
error 字符串 N 执行失败的错误码。该信息仅在status为2时上传,且仅上传error_code字段

step 说明如下:

  1. 准备阶段:设备空闲可升级->获取升级固件信息->等待用户确认是否升级
  2. 下载固件阶段:下载固件开始-下载固件完成-校验固件格式是否正确
  3. 安装固件阶段:安装固件开始-安装固件完成
  4. 完成阶段:安装固件需要重启后才能生效,重装固件后重启会丢失上下文,因此不需要上报此阶段的进度以及结果 ,当设备升级完成且重启后需要将当前固件版本上报给应用。上报指令:平台指令101设备信息上报

注意:

各流程 返回参数说明如下:

  1. 设备在接收到平台指令-206,返回step0status0
  2. 设备查询平台指令-103获取到需要升级的版本信息后,设备准备固件升级就绪等待用户确认升级,返回step0status1
  3. 设备如果固件准备就绪后等待用户确认超过60s,则等待用户确认超时自动取消,返回step0status3,error详见异常情况说明;
  4. 设备收到用户确认升级操作后,进入下载固件阶段,返回step1status0progress当前进度
  5. 设备下载过程中,进度定时更新并返回step1status1progress当前进度
  6. 设备下载完成后,校验固件成功开始安装后,返回step2status0progress0
  7. 设备安装固件成功后,返回step2status1progress100
  8. 设备升级过程中,任何阶段出现异常导致升级失败,返回step当前阶段status2,error详见异常情况说明
  9. 设备升级过程中,用户操作取消升级,返回step当前阶段status3

异常情况说明 如下:

  1. 如果收到固件升级指令设备正忙(执行其他任务)无法执行任务时,设备忙(通用业务异常),任务失败
  2. 如果收到固件升级指令设备故障无法执行任务时,设备故障描述,任务失败
  3. 如果固件准备就绪后等待用户确认超时时,等待用户确认超时,任务失败
  4. 如果固件下载失败时,固件下载失败,任务失败
  5. 如果设备存储空间不足导致固件保存失败时,设备存储空间不足,任务失败
  6. 如果固件下载后发现固件格式错误时,固件格式错误,任务失败
  7. 如果其他异常导致任务失败时,其他异常描述,任务失败

异常错误码请详见错误码说明

云清洁

在用户使用过程中,会出现缺失某一种色彩、文字深浅不一、图片上有明显的线条等打印问题,云清洁功能可以一定程度解决这些问题,改善打印的画质。

云清洁流程图:


participant 用户 as user
participant 应用 as app
participant 设备 as device

user->app: 1、云清洁
app->device: 2、发送[执行云清洁]指令
device->device: 3、任务是否执行确认
device->app: 4、返回清洁中
device->device: 5、清洁打印

Note left of device: 如果设备出现故障打印被暂停
device--app: 返回清洁暂停

Note left of device: 解决故障,恢复打印
device--app: 返回清洁中

Note left of device: 如果取消清洁
device--app: 返回清洁取消,任务结束

Note left of device: 如果清洁失败
device--app: 返回清洁失败,任务结束

device->app: 6、清洁成功
app->user: 7、返回清洁结果

流程说明:

执行云清洁

请求示例:

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_cloud_clean",
        "payload": {
            "task_id": "123",
            "clean_mode": "normal"
        }
    }
}

其中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": ""

        }
    }
}

各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 清洁任务id
clean_status 字符串 Y 清洁状态:cleaning-清洁中,finish-清洁成功,pause-清洁暂停,fail-清洁失败,cancel-清洁取消
error_code 字符串 N 错误码,故障/异常必填,详细描述见下面异常情况说明
error_msg 字符串 N 错误描述,故障/异常必填
error_cause 字符串 N 错误原因,选填。方便调查解决问题

清洁状态clean_status的具体说明如下:

  1. 开始清洁时,返回clean_statuscleaning
  2. 设备在清洁打印过程中出现部分原因会导致打印暂停,返回clean_statuspause,暂停原因见异常情况说明
  3. 当清洁打印因故暂停,在解决故障恢复打印后,返回clean_statuscleaning
  4. 清洁打印失败终止时,返回clean_statusfail,失败原因见异常情况说明
  5. 当用户取消清洁或者收到取消云清洁指令后,返回clean_statuscancel
  6. 当清洁完成后,返回clean_statusfinish

异常情况说明 如下:

  1. 如果收到云清洁指令设备正忙(执行其他任务)无法执行任务时,设备忙(通用业务异常),任务失败
  2. 如果收到云清洁指令设备故障无法执行任务时,设备故障描述,任务失败
  3. 如果收到云清洁指令请求参数不正确无法执行任务时,请求参数错误(通用业务异常),任务失败
  4. 如果设备清洁打印过程中设备故障,需要用户解决可恢复继续清洁打印时,设备故障描述,任务暂停
  5. 如果设备清洁打印过程中设备故障,不能恢复继续清洁打印时,设备故障描述,任务失败
  6. 如果其他异常导致任务失败时,其他异常描述,任务失败

异常错误码请详见错误码说明

取消云清洁

当用户想取消设备云清洁时,可发送本指令,取消此次清洁操作。

请求示例:

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_cloud_clean_cancel"
    }
}

其中cmd固定为server_push_cloud_clean_cancel表示取消云清洁指令,当设备处于云清洁打印中,取消清洁,并上报结果已取消,如果清洁已完成或者没有清洁任务则忽略。 无请求payload

响应示例:

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1584103546,
    "action": 300,
    "data": {
        "cmd": "server_push_cloud_clean_cancel"
    }
}

无响应payload

打印校准

在用户使用过程中,必定会出现文字、图像重影,线条不直歪斜等打印问题,校准可以改善打印的画质。

功能流程图:

participant 用户 as user
participant 应用 as app
participant 设备 as device

user->app: 1、打印校准
app->device: 2、发送[校准打印]指令
device->device: 3、任务是否执行确认
device->app: 4、返回打印中
device->device: 5、打印完一页校准画像
device->app: 6、返回打印中(更新打印页数)

Note left of device: 如果设备出现故障打印被暂停
device--app: 返回校准打印暂停
Note left of device: 解决故障,恢复打印
device--app: 返回校准打印中

Note left of device: 如果取消打印
device--app: 返回校准打印取消,任务结束

Note left of device: 如果打印失败
device--app: 返回校准打印失败,任务结束

device->device: 7、打印完成
device->app: 8、返回校准打印完成

app->user: 9、提示用户打印完成,请根据结果完成设置
user-app: 10、设置校准参数
app->device: 11、发送[校准设置]指令
device->device: 12、校准参数设置
device->app: 13、校准设置结果
app->user: 14、校准设置结果

流程说明:

执行校准打印

应用可通过以下指令向设备设备发起打印校准操作,设备收到此指令后,进入打印校准流程。

请求示例:

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_alignment_print",
        "payload": {
            "task_id": "123"
        }
    }
}

其中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": ""
        }
    }
}

各参数说明如下:

参数 类型 是否必填 说明
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的具体说明如下:

  1. 开始打印时,返回print_statusprinting
  2. 设备在打印过程中出现部分原因会导致打印暂停,返回print_statuspause,暂停原因见异常情况说明
  3. 当校准打印因故暂停,在解决故障恢复打印后,返回print_statusprinting
  4. 打印任务出现失败时,返回print_statusfailerror_codeerror_msg异常情况说明
  5. 当用户取消校准打印或者收到取消校准打印指令后,返回print_statuscancel
  6. 当打印完成后,返回print_statusfinish

异常情况说明 如下:

  1. 如果收到校准打印指令设备正忙(执行其他任务)无法执行任务时,设备忙(通用业务异常),任务失败
  2. 如果收到校准打印指令设备故障无法执行任务时,设备故障描述,任务失败
  3. 如果收到校准打印指令请求参数不正确无法执行任务时,校准打印业务不支持(通用业务异常),任务失败
  4. 如果设备校准打印过程中设备故障,需要用户解决可恢复继续打印时,设备故障描述,任务暂停
  5. 如果设备校准打印过程中设备故障,不能恢复继续打印时,设备故障描述,任务失败
  6. 如果其他异常导致任务失败时,其他异常描述,任务失败

异常错误码请详见错误码说明

取消校准打印

当用户想取消校准打印时,可发送本指令,取消此次校准打印操作。

请求示例:

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_alignment_print_cancel"
    }
}

其中cmd固定为server_push_alignment_print_cancel表示取消校准打印指令,当设备处于校准打印中,取消打印,并上报结果已取消,如果校准打印已完成或者没有执行则忽略。 无请求payload

响应示例:

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1584103546,
    "action": 300,
    "data": {
        "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"
            }] 
        }
    }
}

其中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": ""
        }
    }
}

payload各参数说明如下:

参数 类型 是否必填 说明
task_id 字符串 Y 校准任务id
set_status 字符串 Y 设置状态:success-成功,fail-失败
error_code 字符串 N 错误码,故障/异常必填,详细描述见下面异常情况说明
error_msg 字符串 N 错误描述,故障/异常必填
error_cause 字符串 N 错误原因,选填。方便调查解决问题

注意:

错误码说明

本章节主要定义导致设备功能不可用以及业务执行暂停或者异常结束的错误码定义,错误码主要包含设备故障错误码以及业务异常错误码。

设备故障错误码

设备故障错误码是指设备硬件本身发生故障,会导致部分功能不可使用的故障错误信息,由于不同设备厂商,不同设备型号的故障类型有很多不同,设备故障错误码有厂商自行定义

例如:进纸托盘处无纸、纸张放置不正确、墨盒仓门已打开、进纸托盘处发生卡纸等。

如果设备发生故障时:

  1. 需要上报设备故障状态以及设备故障错误码给应用,上报指令:设备信息上报
  2. 如果此时设备正在执行业务任务且导致任务暂停或者任务异常结束,还需要上报任务执行状态以及错误信息给应用 (请参考业务异常错误码)。

设备故障码要求:

业务异常错误码

业务异常错误码主要是指设备执行业务任务过程中,出现导致任务暂停或者异常结束的业务异常错误信息(非设备硬件本身的故障)。

例如:设备忙(执行A任务不能执行B任务)、请求参数异常(业务请求参数不合法或者不支持)等。

如果设备执行业务任务过程中出现业务异常导致任务暂停或者任务异常结束,需要上报任务执行状态以及业务错误码信息,上报指令根据业务类型选择,例如:云打印-打印任务进度上报、云扫描-执行云打印扫描 等。

异常定义:

业务类型 错误码 错误描述 错误原因 错误原因说明
通用 100001 设备忙 --- 收到新任务请求,因为设备正在其他任务而不能执行当前任务
通用 100002 不支持xxx(具体错误描述由产品定义 不支持的参数:"param1、param2"。(param1、param2为参数属性名) 由于固件版本或者产品配置不正确,导致业务请求参数不支持。错误描述比如:"不支持自动进纸器扫描","不支持A4纸张尺寸"等
通用 100003 设备存储空间不足 --- 由于设备存储空间不足,导致有文件存储的业务任务失败
通用 100004 文件云存储失败 --- 设备将本地文件上传云端保存失败
通用 100999 未知异常描述(详细错误描述由产品定义 导致异常的具体原因,方便后期调查 当处理业务过程中,出现本文档未定义的异常上报,注意 具体描述由产品定义
云打印 201001 文件下载失败 httpStatus信息 开始执行任务后,打印机从云端下载报文失败
云打印 201002 文件格式不支持 --- 打印机下载的报文格式错误或者报文参数不支持
固件升级 204001 等待用户确认超时 --- 固件升级中等待用户确认升级超时
固件升级 204002 固件下载失败 httpStatus信息 固件下载失败
固件升级 204003 固件格式不支持 --- 固件格式错误,无法升级