扫描接口

通过扫描接口可以控制扫描仪进行扫描任务相关操作，并在回调通知中获得扫描结果。

提示

调用接口前请先阅读 『扫描功能概览』 章节，了解扫描任务的整体流程。

创建扫描任务接口 API

注意

• 调用时功夫智盒设备必须是在线状态

• 已正确连接扫描仪、扫描仪已开机并状态正常

• 扫描是独占操作，KIC会对扫描任务加锁，同一个设备不可以同时调用两次扫描，下一次创建扫描必须在前一次扫描任务结束之后（收到 scan.finish 事件回调后），否则会提示相应的错误码。

• 当使用连续扫描模式时，若continuous_wait设为0，则此扫描任务不会自动停止，需要调用 主动停止扫描接口 来进行终止。

• 请不要在扫描仪仍在进行扫描时继续添加纸张。

POST /api/scan/create

• 请求参数（JSON Body）：

名称	类型	必选	默认值	说明
client_uuid	String	是		设备UUID
options	Object	否		扫描任务自定义选项
options.callback_url	String	否		扫描任务的回调通知地址，最长200个字符
options.continuous	Bool	否	false	是否开启连续扫描模式
options.continuous_wait	Integer	否	60	连续扫描等待时间（单位：秒。options.continuous: true 时生效， 值为0时，始终等待 ，需要调用 主动停止扫描接口 来进行终止）
options.blank_page_skip	Bool	否	true	是否需要跳过空白页
options.duplex	Bool	否	true	是否是双面扫描
options.color_type	Integer	否	0	颜色模式。可选值：0 彩色，1 黑白
options.quality	Integer	否	90	图像质量，可选值：1-100 (值越小最终输出的文件越小，如网络环境上行速率较低，可适当调低质量至85以下)
options.resolution	Integer	否	200	扫描分辨率DPI，可选值：100,150,200,240,300,400,600,1200 (取决于打印机支持的DPI)
options.encrypt	Bool	否	false	是否启用数据加密，参见 『KHES 加密』
options.direct_mode	Integer	否	0	直传模式。可选值：0 不开启，1 仅开启直传（不上传最终的PDF），2 同时直传（仍上传最终的PDF） 开启2模式时，上传的数据量会较多，请确保网络上行带宽足够。 详见 『直传模式』
options.direct_page_size	Integer	否	2	直传模式时，每次传输的页面数量 （取值范围：1-10）。详见 『直传模式』
options.direct_addr	String	否		直传开启时的直传地址URL（http或https，支持HTTP2，最长200个字符）。开启直传时必填 详见 『直传模式』

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Object	否	响应数据
data.uuid	String	否	此次扫描任务的UUID （收到响应后请尽快保存下来，扫描事件回调通知中会携带此UUID）
data.expires_at	Integer	否	此次扫描任务的过期时间（Unix时间戳，单位：秒。 达到过期时间之后，扫描任务会自动销毁，任务信息无法查询，一般为24小时之后 ）
data.exist_uuid	String	否	code为30204时返回 若当前存在扫描任务，则返回该扫描任务的UUID

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "expires_at": 1629119239,
    "uuid": "4153814d-xxxx-xxxx-xxxx-0bd9a88d5e7a"
  }
}

• 失败示例：

HTTP Status 200

{
  "code": 30204,
  "msg": "当前已存在扫描动作",
  "data": {
    "exist_uuid": "4153814d-xxxx-xxxx-xxxx-0bd9a88d5e7a" // 已存在任务的UUID
  }
}

查看全部状态码

主动停止扫描接口 API

提示

• 非连续扫描或连续扫描模式都可以使用此接口进行主动停止操作，调用后当前扫描任务会立即停止。

• 主动停止扫描操作是设备维度的API，无需指定扫描任务UUID。

• 若设备在扫描过程遇到突然断电等特殊情况，导致扫描结果无法正确上报时（例如错误码30204），也可以通过此接口刷新扫描状态。

POST /api/scan/stop

• 请求参数（JSON Body）：

名称	类型	必选	说明
client_uuid	String	是	设备UUID

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Null	是	响应数据（无）

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": null
}

查看全部状态码

获取当前任务接口 API

POST /api/scan/current

• 请求参数（JSON Body）：

名称	类型	必选	说明
client_uuid	String	是	设备UUID

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Object	否	响应数据
data.exist	Bool	否	当前是否有扫描任务进行中
data.scan_uuid	String	否	若当前存在扫描任务，则返回该扫描任务的UUID

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "exist": true,
    "scan_uuid": "26568435-xxxx-xxxx-xxxx-3c4ac0cea0ea"
  }
}

查看全部状态码

查询扫描任务接口 API

POST /api/scan/info

• 请求参数（JSON Body）：

名称	类型	必选	说明
client_uuid	String	是	设备UUID
scan_uuid	String	是	扫描任务UUID

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Object	否	响应数据
data.action_ack	Bool	否	终端是否已接收
data.action_ack_at	Integer	否	终端接收时的Unix时间戳（单位：毫秒）
data.finished	Bool	否	是否已完成
data.item_size	Integer	否	当前已扫描的扫描数据文件数量
data.total_pages	Integer	否	当前已扫描的总页数
data.total_file_size	Integer	否	当前已扫描的文件总大小（单位：KB）direct_mode=1时无值
data.error_code	Integer	否	扫描流程错误码，详见 扫描错误码
data.created_at	Integer	否	扫描任务创建时的Unix时间戳（单位：毫秒）
data.finished_at	Integer	否	扫描任务完成时的Unix时间戳（单位：毫秒）
data.expires_at	Integer	否	此次扫描任务的过期时间（Unix时间戳，单位：秒。 达到过期时间之后，扫描任务会自动销毁，任务信息无法查询，一般为24小时之后 ）

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "action_ack": true,
    "action_ack_at": 1628935153236,
    "created_at": 1628935097368,
    "error_code": 0,
    "expires_at": 1729021497,
    "finished": true,
    "finished_at": 1628935153236,
    "item_size": 1,
    "total_file_size": 1743,
    "total_pages": 6
  }
}

查看全部状态码

查询扫描数据接口 API

提示

此接口为分页查询接口，默认每页20条数据

POST /api/scan/item_data

• 请求参数（JSON Body）：

名称	类型	必选	说明
client_uuid	String	是	设备UUID
scan_uuid	String	是	扫描任务UUID
page	Integer	是	分页查询页码（从1自增，范围：1-1000，默认值：1）

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Object	否	响应数据
data.scan_uuid	String	否	扫描任务的UUID
data.total	Interger	否	分页属性，数据总条数
data.page_size	Integer	否	分页属性，每页数量
data.page	Integer	否	分页属性，当前页码
data.items	Object Array	否	扫描数据对象数组
data.items[Index].item_id	Integer	否	扫描数据的ID，从1开始自增
data.items[Index].pages	Integer	否	PDF页数，扫描面数
data.items[Index].file_size	Integer	否	文件大小（单位：KB，direct_mode=1时无值）
data.items[Index].upload_spent	Integer	否	上传耗时（单位：秒，direct_mode=1时无值）
data.items[Index].check_sum	String	否	文件的md5值，direct_mode=1时无值
data.items[Index].scanned_at	Integer	否	此次扫描完成时间戳（单位：毫秒）
data.items[Index].cipher	String	否	加密密文（Hex编码，当开启数据加密时有值，参见 『KHES 加密』）direct_mode=1时无值
data.items[Index].temp_download_url	String	否	文件临时下载链接（一般有效期为 1小时）direct_mode=1时无值

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "check_sum": "bfd10c4d719565a4a10f8e21b4faa365",
        "cipher": "",
        "file_size": 1743,
        "item_id": 1,
        "pages": 6,
        "scanned_at": 1628935113048,
        "temp_download_url": "xxxx",
        "upload_spent": 1
      },
      {
        "check_sum": "f17944d9a59f60e7116567f886d6163b",
        "cipher": "",
        "file_size": 593,
        "item_id": 2,
        "pages": 2,
        "scanned_at": 1628931561769,
        "temp_download_url": "xxxxx",
        "upload_spent": 0
      }
    ],
    "scan_uuid": "f8e2cdf6-xxxx-xxxx-xxxx-d036a8cea2a1",
    "page": 1,
    "page_size": 20,
    "total": 2
  }
}

查看全部状态码