# 回调通知
KIC支持一系列的事件（Event）回调通知。在业务流程中当触发这些事件时，KIC会通过HTTP POST方式将事件的相关信息回调至您设置的回调地址（CallbackURL）上。
TIP
回调通知对于事件的处理是单向的，它仅支持将事件推送给 Web 服务，并不关心 Web 服务的返回。
借助回调通知可以完成设备在线状态、上下线记录，实时接收扫描结果等诸多业务。
# 回调消息
回调请求URI：
设备 相关事件回调（如：如设备上线、离线），回调至应用设置的CallbackURL，若未设置则不进行回调。
业务流程 触发的时间回调（如：打印、扫描），回调至业务接口设置的CallbackURL，若未设置则不进行回调。
回调请求方法（Request Method）：POST
回调请求头（Request Header）：
| 名称 | 说明 |
|---|---|
| User-Agent | 固定为：KIC |
| Content-Type | 固定为：application/json |
| X-KIC-Callback-ID | 回调消息ID，例如：1607df56-5077-478e-a252-2054f1292ba6 |
| X-KIC-Signature | 回调消息签名，可用于接收端验证回调消息的合法性，详见 消息签名 |
- 回调请求消息体（Request Body）：
消息体固定为JSON 格式，包含以下结构：
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| event | String | 是 | 事件名称 |
| app_key | String | 是 | 对应应用的AppKey |
| timestamp | Integer | 是 | 消息发出前的Unix时间戳（毫秒） |
| client_uuid | String | 否 | 对应触发事件的设备UUID |
| data | Object | 否 | 相关对应事件的业务详细数据，详见 事件数据 |
请求Body示例：
{
"event": "scan.ack", // 设备已接收扫描指令
"app_key": "xxxxxxx",
"timestamp": 1628843904245,
"client_uuid": "941e2dad-xxxx-xxxx-xxxx-ec78d66e227d",
"data": {
"uuid": "e7f761e2-8eee-401f-95d8-78761bf69004"
}
}
2
3
4
5
6
7
8
9
- 回调请求的响应（Respons）：
HTTP状态码必须为：HTTP StatusOK （Status Code 200） ，Header：不做要求，Body： 不做要求（建议为空）。
注意
当Web服务接收到回调请求后，需要在 5秒 内给出任意的 HTTP StatusOK （Status Code 200） Response响应（建议返回空字符串）。
若5秒内未完成响应或响应的状态码不是200，则认为此次回调失败。失败后会再进行3次重试，分别在前次回调失败后的 8秒、13秒、21秒。
# 消息签名
KIC会对每个发出的回调消息体进行HMAC-SHA1算法签名，可用于接收端验证回调消息的合法性。
HMAC-SHA1签名内容：Request Body。
HMAC-SHA1签名秘钥：对应应用的AppSecret。
签名验证方法：
读取回调请求Header中的X-KIC-Signature，存为字符串remoteSign
读取回调请求的Body，存为字符串bodyStr
获取对应应用的AppSecret，存为字符串key
使用HMAC-SHA1算法对bodyStr进行本地签名，秘钥为key，得到签名结果localSign字符串
对比localSign与remoteSign字符串，若完全一致表示签名合法
TIP
消息签名的验证是可选的，在调试时可以不进行校验。若在生产环境使用时，强烈建议您对消息签名进行校验。
# 事件列表
目前支持的回调事件：
| 事件名称（Event） | 事件类型 | 说明 |
|---|---|---|
| client.online | 设备 | 设备上线 |
| client.offline | 设备 | 设备离线 |
| client.scanner_state | 设备 | 扫描仪状态变更 |
| client.printer_state | 设备 | 打印机状态变更 |
| client.gpio | 设备 | GPIO触发器事件 |
| client.scanner | 设备 | 扫描仪触发器事件 |
| scan.ack | 业务流程 | 扫描流程，终端已收到扫描任务 |
| scan.item_data | 业务流程 | 扫描流程，本次扫描的PDF数据（如开启连续扫描，则会收到多次） |
| scan.finish | 业务流程 | 扫描流程，回调扫描的最终状态 |
| print.ack | 业务流程 | 打印流程，终端已收到打印任务 |
| print.start | 业务流程 | 打印流程，已开始打印 |
| print.finish | 业务流程 | 打印流程，已结束打印 |
注意
如未设置对应的回调地址（CallbackURL），则不会进行回调通知
# 事件数据
事件数据对象位于请求消息体的data字段，不同事件会收到不同的事件数据。
# client.online
设备上线
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| ip | String | 是 | 设备的IP地址 |
| connected_at | Integer | 是 | 设备上线连接时的Unix时间戳（单位：毫秒） |
# client.offline
设备离线
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| disconnect_at | Integer | 是 | 设备离线时的Unix时间戳（单位：毫秒） |
# client.scanner_state
扫描仪状态变更
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| connected | Bool | 是 | 是否已连接扫描仪 |
| supported | Bool | 是 | 扫描仪型号是否支持 |
| make | String | 是 | 扫描仪厂家名称 |
| model | String | 是 | 扫描仪型号名称 |
| connection_type | String | 是 | 扫描仪连接方式 |
# client.printer_state
打印机状态变更
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| connected | Bool | 是 | 是否已连接打印机 |
| supported | Bool | 是 | 打印机型号是否支持 |
| make | String | 是 | 打印机厂家名称 |
| model | String | 是 | 打印机型号名称 |
| connection_type | String | 是 | 打印机连接方式 |
| error_code | Integer | 是 | 打印机错误状态码 详见 打印机错误码 |
# client.gpio
设备GPIO触发器事件
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| port | String | 是 | GPIO编号（K1只有两种：GPIO1、GPIO2） |
| method | Integer | 是 | 触发的方式 取值： 0 触发或按下一次、 1 长按或长时间触发（超过1秒）、 2 连续触发或按下两次（1秒内） |
| trigger_at | Integer | 是 | 触发时的Unix时间戳 （单位：毫秒） |
# client.scanner
扫描仪触发器事件
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| method | Integer | 是 | 触发的方式 取值： 0 物理按钮按下 |
| trigger_at | Integer | 是 | 触发时的Unix时间戳 （单位：毫秒） |
# scan.ack
扫描流程，终端已收到扫描任务
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| scan_uuid | String | 是 | 扫描任务的UUID |
| action_ack_at | Integer | 是 | 任务接收时的Unix时间戳 （单位：毫秒） |
# scan.item_data
扫描流程，本次扫描的PDF文件数据（如开启连续扫描，则会收到多次）
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| scan_uuid | String | 是 | 扫描任务的UUID |
| item_id | Integer | 是 | 此次扫描数据的ID，从1开始自增 |
| pages | Integer | 是 | PDF页数，扫描面数 direct_mode=1时无值 |
| file_size | Integer | 是 | 文件大小（单位：KB，direct_mode=1时无值） |
| upload_spent | Integer | 是 | 上传耗时（单位：秒，direct_mode=1时无值） |
| check_sum | String | 是 | 文件的md5值，direct_mode=1时无值 |
| scanned_at | Integer | 是 | 此次扫描完成时间戳（单位：毫秒） |
| cipher | String | 否 | 加密密文（Hex编码）direct_mode=1时无值 |
| temp_download_url | String | 是 | 文件临时下载链接（一般有效期为 1小时）direct_mode=1时无值 |
# scan.finish
扫描流程，扫描结束，扫描的最终状态
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| scan_uuid | String | 是 | 扫描任务的UUID |
| item_size | Integer | 是 | 扫描数据的数量，即item_data的数量 |
| total_pages | Integer | 是 | 总页数 |
| total_file_size | Integer | 是 | 总文件大小（单位：KB）direct_mode=1时无值 |
| error_code | Integer | 是 | 扫描流程错误码 ，当扫描流程发生异常，此字段非0 详见 扫描错误码 |
| finished_at | Integer | 是 | 扫描任务完成时间戳（单位：毫秒） |
# print.ack
打印流程，终端已收到打印任务
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| print_uuid | String | 是 | 打印任务的UUID |
| action_ack_at | Integer | 是 | 任务接收时的Unix时间戳 （单位：毫秒） |
# print.start
打印流程，已开始打印
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| print_uuid | String | 是 | 打印任务的UUID |
| started_at | Integer | 是 | 打印开始时的Unix时间戳 （单位：毫秒） |
| pages | Integer | 否 | 预估页数 （根据文件与份数设置的评估值，非实际打印页数） |
# print.finish
打印流程，已结束打印
| 名称 | 类型 | 必选 | 说明 |
|---|---|---|---|
| print_uuid | String | 是 | 打印任务的UUID |
| finished_at | Integer | 是 | 打印结束时的Unix时间戳 （单位：毫秒） |
| error_code | Integer | 是 | 打印错误码（当打印流程发生异常，打印失败时，此字段非0） 详见 打印错误码 |
| file_size | Integer | 是 | 终端下载到的文件大小（单位：KB） |
| download_spent | Integer | 是 | 终端下载文件耗时（单位：秒） |
| pages | Integer | 否 | 预估页数 （根据文件与份数设置的评估值，非实际打印页数） |
| printed_pages | Integer | 否 | 使用严格模式时的实际打印面数 （只有在使用严格模式时有值） 注意：此值为打印面数，如打印的文档页数为3页并启用双面打印模式，此时值为4 （空白面也会计算，当启用双面打印时，printed_pages/2 即可得到实际使用的纸张数量） |