直传模式

KIC提供了扫描数据实时直传的高级能力，不开启直传模式时，每次扫描结束后可以获取到此次扫描结果的完整PDF。

开启直传模式时可以在扫描过程中，将每页或多页的扫描图像（JPEG）实时直传至您的服务器上，可实现实时的扫描页面图像数据流获取。

直传模式是扫描过程中对扫描页面数据流的并行处理，单次扫描和连续扫描都可以开启实时直传，并且可以通过direct_mode来控制是否上传最终的PDF文件。

TIP

实时直传数据不会经过KIC服务器。

直传支持上传至公网服务器或内网的设备中。

直传与正常扫描方式可以同时进行（direct_mode: 2, 即可获得直传数据又可以获得最终的PDF结果）

注意

页面数据的直传是串行的，盒子终端会对每页或多页（取决于direct_page_size）进行逐一上传，请确保您的服务端的带宽充足、能稳定的响应请求数据。接收数据后能尽快给出正常响应以提升传输效率。（最好在1秒内）

直传模式传输的页面数据不支持KHES加密，建议使用HTTPS加密协议进行接收直传数据，并可以通过开启HTTP2协议来加快传输效率。

开启直传

• 调用 『创建扫描任务接口』 并将options.direct_mode设为1或2 （1 仅开启直传（不上传最终的PDF），2 同时直传（仍上传最终的PDF）） 。

• 设置options.direct_page_size为每次传输的页面数量 （取值范围：1-10，默认为2） 。如设为1，每个页面都会传输一次数据，如开启双面，则一页双面的纸张会传输两次页面数据。数值越大则每次传输的数据量就越大，建议使用1或2来提升整体的实时效率。

• 设置options.direct_addr用于接收直传数据的服务端或终端接口地址（支持http、https），在页面数据生成后，盒子终端会通过POST application/json的形式向该地址发送，当扫描结束时通过PUT请求发送扫描完成结果通知。

提示

每次直传请求在收到后请尽快给出响应（最好在1秒内），如超过30秒（包含网络建连、传输时间）则认为请求超时，会继续重试 3 次。

响应速度越快则实时性越高。

注意

请确保您的服务端或终端的网关（如Nginx）和应用服务器程序的client_max_body_size 设置的值足够大（Nginx默认为1M），否则无法正确接收数据，当direct_page_size设为2或更大值时，请求body的大小往往在1M以上。建议根据您的应用环境将网关及应用服务器的最大请求Body设为20M以上，否则有可能请求会被拦截，返回413 Request Entity Too Large

接收直传数据 Callback

在服务端或内网终端上实现一个HTTP接口并接收页面实时直传数据（接口地址为创建扫描任务时设置的options.direct_addr，通过HTTP POST请求发送）。

建议使用HTTPS（HTTP2）接口来提高安全性与传输效率

• 请求类型（Request Method）：POST
• 请求头（Request Header）：

名称	说明
User-Agent	固定为：KIC-Client
Content-Type	固定为：application/json

• 请求消息体（Request Body）：

消息体固定为JSON 格式，包含以下结构：

名称	类型	必选	说明
client_uuid	String	是	设备UUID
scan_uuid	String	是	扫描任务UUID
item_id	Integer	是	扫描数据的批次ID。 与scan.item_data回调通知中的item_id一致。
pages	Object Array	是	页面数据对象数组 （按页面顺序排序，数量取决于options.direct_page_size，最后一次直传的数量可能小于该数值）
pages[Index].paper_number	Integer	是	此页面的纸张页数（第几页纸张，当开启双面扫描并开启跳过空白页时，可能出现跳页，识别到空白页不传输）
pages[Index].page_number	Integer	是	此页面的页面数（第几面，如第二张纸的面为3，当开启双面扫描并开启跳过空白页时，可能出现跳页，识别到空白页不传输）
pages[Index].front	Bool	是	此页面是否为正面（扫描稿件朝向扫描仪的一面为正面）
pages[Index].file_type	String	是	此页面数据的文件类型（默认为jpg）
pages[Index].file_size	Integer	是	此页面数据的文件大小，字节数
pages[Index].check_sum	String	是	此页面数据的文件MD5校验值
pages[Index].data	String	是	此页面数据的文件内容（base64编码，不包含 类型前缀data:image/jpeg;base64。如需存储该文件，直接将base64解码为字节码写入jpg文件即可）

• 直传请求Body示例：

{
    "client_uuid": "941e2dad-xxxx-xxxx-xxxx-ec78d66e227d",
    "scan_uuid": "xxxxxxx",
    "item_id": 1,
    "pages": [
      {
        "paper_number": 1,
        "page_number": 1,
        "front": true,
        "file_type": "jpg",
        "file_size": 4231105,
        "check_sum": "xxxxxxxxxxxxxx",
        "data": "xxxxxxx...."
      },
      {
        "paper_number": 1,
        "page_number": 2,
        "front": false,
        "file_type": "jpg",
        "file_size": 6237825,
        "check_sum": "xxxxxxxxxxxxxx",
        "data": "xxxxxxx...."
      },
      {
        "paper_number": 2,
        "page_number": 3,
        "front": true,
        "file_type": "jpg",
        "file_size": 6237825,
        "check_sum": "xxxxxxxxxxxxxx",
        "data": "xxxxxxx...."
      },
      ...
    ]
}

接收扫描完成结果 Callback

在服务端或内网终端上实现一个HTTP接口并接收扫描任务完成结果（接口地址为创建扫描任务时设置的options.direct_addr，通过HTTP PUT请求发送）。

当本次扫描任务结束时，并且在所有直传数据传输完成后，盒子终端会 同步的 发出该完成结果通知。

• 请求类型（Request Method）：PUT
• 请求头（Request Header）：

名称	说明
User-Agent	固定为：KIC-Client
Content-Type	固定为：application/json

• 请求消息体（Request Body）：

消息体固定为JSON 格式，包含以下结构：

名称	类型	必选	说明
client_uuid	String	是	设备UUID
scan_uuid	String	是	扫描任务UUID
error_code	Integer	是	同回调通知中的 error_code， 扫描流程错误码 当扫描流程发生异常，此字段非0 详见 扫描错误码
item_size	Integer	是	扫描批次的数量，即item_data的数量
total_pages	Integer	是	总扫描页面数（开启跳过空白页时，不含空白页数量）
state	String	是	取值：finish 扫描完成

• 直传请求Body示例：

{
  "client_uuid": "26568435-xxxx-xxxx-xxxx-3c4ac0cea0ea",
  "scan_uuid": "11a30100-xxxx-xxxx-xxxx-066e41ffd658",
  "error_code": 0,
  "item_size": 4,
  "total_pages": 12,
  "state": "finish"
}