云打印接入协议1.1

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

时间 版本 修订人 修订说明
2020-07-11 1.0 徐超国 整理并发布打印接入协议初版
2020-08-20 1.1 胡金喜 1. 新功能:云扫描、证件扫描、固件升级
2. 优化协议,增加接入指南

云打印设备接入指南

连接平台接入介绍

设备接入平台有详细介绍,请仔细阅读得力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 设备当前名称,没有则传设备编号
printer_type 字符串 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-墨盒未安装,2-墨盒未安装(兼容老固件)
其他表示未知墨盒异常
inkbox_status_des 字符串 Y 墨盒状态描述:异常情况必传,保持和设备显示一致,以产品定义为准
inkbox_colors inkbox_color列表 Y inkbox_color 墨盒颜料的信息列表

一个墨盒表示一个单独更换的整体,常见的彩色墨盒类型有3种

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

设备错误上报

当设备发生故障或者解除故障时都需要在本地记录故障信息,并通过本指令向应用上报故障信息。

注意,该指令与应用指令-设备信息上报重复,已废弃。

请求示例:

{
  "mid": "123456",
  "from": "M2500ADNW_12345678",
  "to": "511542236802977792",
  "action": 300,
  "time": 1584079078,
  "data": {
    "cmd": "printer_push_report_error",
    "payload": {
      "printer_name": "M2500DW-L09E",
      "firmware_version": "HD_2.00.014",
      "work_status": "busy",
      "error_code": "-1",
      "error_msg": "",
      "total_page_count": "0",
      "total_paper_count": "0",
      "error_paper_count": "0",
      "error_time": "1584079078"
    }
  }
}

其中cmd固定为printer_push_report_error表示设备错误上报,payload各参数说明如下:

参数 类型 是否必传 说明
printer_name 字符串 N 设备名称
firmware_version 字符串 Y 设备当前固件版本
work_status 字符串 Y 设备状态。包括:idle-就绪,busy-繁忙,error-故障。
error_code 字符串 N 故障时错误码,
error_msg 字符串 N 故障时错误描述
total_page_count 字符串 Y 发生故障时总打印页数 累计
total_paper_count 字符串 Y 发生故障时总打印张数 累计
error_paper_count 字符串 Y 打印错误纸张数(卡纸)累计总纸张数
error_time 字符串 Y 发生故障或者回复故障的时间,精确到s

响应示例:

云打印

功能流程图:


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

user->app: 1、选择文件打印
app->app: 2、打印报文转换
app->device: 3、发送[打印任务通知]指令
device->app: 4、发送[打印任务执行]指令
app--device: 5、返回执行任务详情
device--device: 6、开始打印
device->app: 7、返回任务进度:打印中
device--device: 8、下载报文且打印完成一页
device->app: 9、返回任务进度:已打印页数

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": "0",
      "error_msg": "",
      "printed_page_count": "0",
      "printed_paper_count": "0"
    }
  }
}

其中cmd固定为printer_push_print_progress表示打印任务进度上报,请求payload各参数说明如下:

参数 类型 是否必传 说明
task_id 字符串 Y 任务ID
print_status 字符串 Y 任务状态:printing-打印中,finish-成功,fail-失败,cancel-取消。
error_code 字符串 N 失败时错误码:1-设备正忙,2-下载报文连接服务失败,3-下载报文超时,
4-报文格式不支持,5-报文参数不合法,6-设备故障,9-其他异常
error_msg 字符串 N 打印失败描述
printed_page_count 字符串 Y 已打印页数(面数)
printed_paper_count 字符串 Y 已打印成功的纸张数

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

  1. 准备打印时,返回print_statusprinting
  2. 打印过程中,每打印完一页时,返回print_statusprintingprinted_page_count已打印页数printed_paper_count已打印纸张数
  3. 打印任务全部完成时,返回print_statusfinishprinted_page_count已打印页数printed_paper_count已打印纸张数
  4. 打印任务出现失败终止时,返回print_statusfailprinted_page_count已打印页数printed_paper_count已打印纸张数
  5. 打印任务中,取消打印或者收到指令-取消打印任务时,返回print_statuscancelprinted_page_count已打印页数printed_paper_count已打印纸张数

当打印失败异常,异常情况说明如下:

  1. 如果收到扫描指令时设备正忙,返回print_statusfail,同时error_code1error_msg设备忙
  2. 如果打印过程中,下载报文连接服务器失败时,返回print_statusfail,同时error_code2error_msg连接服务器失败
  3. 如果打印过程中,下载报文超时时,返回print_statusfail,同时error_code3error_msg下载报文超时
  4. 如果打印过程中,打印报文格式不支持时,返回print_statusfail,同时error_code4error_msg报文格式不支持
  5. 如果打印过程中,打印报文参数不支持时,返回print_statusfail,同时error_code5error_msg打印参数不支持,不支持的参数信息是:(多个参数逗号隔开);
  6. 如果打印过程中,设备出现故障,超过半小时不解决,返回print_statusfail,同时error_code6error_msg设备故障
  7. 如果打印出现其他异常,返回print_statusfail,同时error_code9error_msg失败原因

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

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

响应示例:

取消打印任务

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

请求示例:

{
  "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 字符串 扫描任务id
scan_source 字符串 扫描源:Auto-自动识别,Flat-平板,ADF-自动进纸器
paper_size 字符串 纸张尺寸:A4
dpi 整型 扫描dpi
image_type 字符串 图片类型,支持:jpg、png
color 字符串 颜色: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": "",
            "image_info":{
                "image_url": "https://xxxx",
                "image_type": "jpg",
                "image_index": "1"
            }

        }
    }
}

响应payload各参数说明如下:

参数 类型 是否必填 描述
task_id 字符串 扫描任务id
cloud_scan_status 字符串 扫描状态:start-扫描就绪,scanning-扫描中,page_done-单页扫描完成,
finish-完成,fail-失败,cancel-取消。
error_code 字符串 异常code:1-设备忙,2-设备故障无法扫描,3-进纸器无纸,4-云存储保存图片异常,
5-单次结果返回异常,6-扫描参数不支持,9-其他异常。详细描述见下面异常情况说明
error_msg 字符串 异常说明,当扫描失败时传
image_info json对象 图片信息:设备扫描完一张时传

image_info各参数说明如下:

参数 类型 是否必填 描述
image_url 字符串 图片网络地址
image_type 字符串 图片类型,支持:jpg、png
image_index 整型 图片顺序从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_statuscancel

当扫描出现异常,异常情况说明如下:

  1. 如果设备收到扫描指令时设备正忙,返回cloud_scan_statusfailerror_code1error_msg设备忙
  2. 如果设备收到扫描指令时因设备故障无法扫描时,返回cloud_scan_statusfailerror_code2error_msg扫描故障
  3. 如果使用进纸器扫描时进纸器无纸,返回cloud_scan_statusfailerror_code3error_msg进纸器无纸
  4. 如果设备扫描完成后,上传图片到云存储接口请求失败(默认重试3次),返回cloud_scan_statusfail,同时error_code4error_msg云存储保存图片异常
  5. 如果设备扫描完成后,单次扫描结果返回失败(默认重试3次),返回cloud_scan_statusfail,同时error_code5error_msg单次结果返回异常
  6. 如果收到的指令参数不支持或者无效,返回cloud_scan_statusfailerror_code6error_msg参数不支持:dpi,image_type(多个参数以逗号隔开);
  7. 如果扫描过程中出现其他异常,则返回cloud_scan_statusfailerror_code9error_msg具体原因

取消云扫描

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

请求示例:

{
    "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 字符串 扫描任务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 字符串 扫描任务id
paper_size 字符串 纸张尺寸:A4
dpi 整型 扫描dpi
image_type 字符串 图片类型,支持:jpg、png
color 字符串 颜色: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": "",
            "image_info":{
                "image_url": "https://xxxx",
                "image_type": "jpg",
                "image_index": "1"
            }
        }
    }
}

响应payload各参数说明如下:

参数 类型 是否必填 描述
task_id 字符串 扫描任务id
credential_scan_status 字符串 扫描状态:start-扫描就绪,scanning-扫描中,page_done-单页扫描完成,
finish-完成,fail-失败,cancel-取消。
error_code 字符串 异常code:1-设备忙,2-设备故障无法扫描,3-云存储保存图片异常,4-单次结果返回异常,
5-等待扫描确认超时,6-扫描参数不支持,9-其他异常。详细描述见下面异常情况说明
error_msg 字符串 异常说明,当扫描失败时必传
image_info json对象 图片信息:设备扫描完一张时传

image_info各参数说明如下:

参数 类型 是否必填 描述
image_url 字符串 图片网络地址
image_type 字符串 图片类型,支持:jpg、png
image_index 整型 图片顺序从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. 当设备等待状态,用户在设备完成扫描或者收到完成证件扫描指令时,设备结束扫描,返回credential_scan_statusfinish
  6. 如果设备扫描过程中,用户在设备上取消扫描或者收到取消证件扫描指令时,设备取消扫描,返回credential_scan_statuscancel

当扫描出现异常,异常情况说明如下:

  1. 如果设备收到扫描指令时设备正忙,返回credential_scan_statusfail,同时error_code1error_msg设备忙
  2. 如果设备收到扫描指令时因设备故障无法扫描时,返回credential_scan_statusfailerror_code2error_msg扫描故障
  3. 如果设备扫描完成后,上传图片到云存储接口请求失败(默认重试3次),返回credential_scan_statusfailerror_code3error_msg云存储保存图片异常
  4. 如果设备扫描完成后,单次扫描结果返回失败(默认重试3次),返回credential_scan_statusfailerror_code4error_msg单次结果返回异常
  5. 如果设备扫描完一张等待时间超过60s时,返回credential_scan_statusfailerror_code5error_msg等待扫描超时
  6. 如果收到的指令参数不支持或者无效,返回credential_scan_statusfailerror_code6error_msg参数不支持:dpi,image_type(多个参数以逗号隔开);
  7. 如果扫描过程中出现其他异常,则返回credential_scan_statusfailerror_code9error_msg具体原因

取消证件扫描

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

请求示例:

{
    "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 字符串 扫描任务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 字符串 扫描任务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 字符串 扫描任务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时上传。

step 说明如下:

  1. 准备阶段:设备空闲可升级->获取升级固件信息->等待用户确认是否升级
  2. 下载固件阶段:下载固件
  3. 安装固件阶段:安装固件

注意

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

  1. 设备在接收到平台指令-206,返回step0status0
  2. 设备查询平台指令-103获取到需要升级的版本信息后,step0status1
  3. 设备收到用户确认升级操作后,进入下载固件阶段,返回step1status0progress当前进度
  4. 设备下载过程中,进度定时更新返回step1status1progress当前进度
  5. 设备下载完成后,校验固件成功开始安装后,返回step2status0progress0
  6. 设备安装固件成功后,返回step2status1progress100
  7. 设备升级过程中,用户操作取消升级,返回step当前阶段status3

当设备升级出现异常,异常说明如下:

  1. 设备在接收到平台指令-206,设备正忙,返回step0status2error1001
  2. 设备在等待确认升级过程中,超过60s用户没有确认或者取消,返回step0status2error1002
  3. 设备下载固件阶段,固件下载失败,返回step1status2error1003
  4. 设备下载固件阶段,存储空间不足,返回step1status2error1004
  5. 设备下载完成后,校验不通过,返回step2status2error1005
  6. 设备出现其他异常,返回step当前阶段status2error1000

error错误码定义:

error 说明 适用阶段
1000 未知异常 ALL
1001 设备繁忙 准备阶段
1002 等待用户确认超时 准备阶段
1003 固件下载失败 下载固件阶段
1004 存储空间不足 下载固件阶段
1005 固件不匹配 安装固件阶段