打印接口

通过打印接口可以获得当前打印机的能力、完成打印任务相关操作。

提示

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

获取打印机能力接口 API

获取当前打印机的能力信息。

GET /api/print/capability

• 请求参数（Query String）：

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

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Object	否	响应数据
data.make	String	否	打印机厂家名称
data.model	String	否	打印机型号
data.support_strict	Bool	否	是否支持严格模式
data.color_mode	String Array	否	支持的色彩模式 详见 参数常量
data.media_sizes	Object Array	否	支持的介质尺寸
data.media_sizes[Index].media_size	String	否	介质尺寸名称 详见 参数常量
data.media_sizes[Index].media_types	Object Array	否	支持的介质类型
data.media_sizes[Index].media_types[Index].media_type	String	否	介质类型名称 详见 参数常量
data.media_sizes[Index].media_types[Index].duplex	String Array	否	支持的双面打印模式 详见 参数常量
data.media_sizes[Index].media_types[Index].borderless	Bool	否	是否支持无边距打印
data.media_sizes[Index].media_types[Index].quality	String Array	否	支持的打印质量模式 详见 参数常量
data.media_sizes[Index].media_types[Index].input_slot	String Array	否	支持的进纸器模式 详见 参数常量

提示

• 色彩模式是打印机的属性，位于根节点

• 打印机一般支持多种介质尺寸，其中每个介质尺寸支持多种介质类型，每个介质类型有不同的能力参数

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "make": "EPSON",
    "model": "M1170 Series",
    "support_strict": true,
    "color_mode": [
      "KIC_CM_MONO"
    ],
    "media_sizes": [
      {
        "media_size": "KIC_MS_A4",
        "media_types": [
          {
            "media_type": "KIC_MT_PLAIN",
            "duplex": [
              "KIC_DP_NONE",
              "KIC_DP_NOTUMBLE",
              "KIC_DP_TUMBLE"
            ],
            "borderless": false,
            "quality": [
              "KIC_QU_HIGH",
              "KIC_QU_NORMAL"
            ],
            "input_slot": [
              "KIC_IS_AUTO",
              "KIC_IS_CASS1",
              "KIC_IS_REAR"
            ]
          },
          {
            "media_type": "KIC_MT_PHOTO",
            "duplex": [
              "KIC_DP_NONE"
            ],
            "borderless": false,
            "quality": [
              "KIC_QU_HIGH",
              "KIC_QU_NORMAL"
            ]
          }
        ]
      },
      ...
    ]
  }
}

• 错误示例：

HTTP Status 200

{
  "code": 30302,
  "msg": "不支持的打印机型号",
  "data": null
}

查看全部状态码

创建打印任务接口 API

注意

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

• 已正确连接打印机、打印机已开机并状态正常、打印机墨水或硒鼓充足、纸张充足并正确摆放

• PDF文件的页面尺寸需要与media_size一致

POST /api/print/create

• 请求参数（JSON Body）：

名称	类型	必选	默认值	说明
client_uuid	String	是		设备UUID
file_type	String	是		打印文件类型。可选值：pdf、jpg
file_url	String	否		打印文件的URL （最长200个字符，file_url 与 file_content 必须二选一）
file_content	String	否		打印文件的内容 Base64编码 （file_url 与 file_content 必须二选一）
file_check_sum	String	否		文件的MD5 Check Sum值。 如非空，则会在打印前校验(如启用加密，取加密后文件的MD5值)。 不传即不校验。
options	Object	否		打印任务自定义选项
options.callback_url	String	否		打印任务的回调通知地址，最长200个字符
options.direct	Bool	否	false	是否开启直传模式 详见 直传模式
options.strict	Bool	否	false	是否开启严格模式 详见 严格模式
options.encrypt	Bool	否	false	是否启用数据加密 参见 『KHES 加密』
options.cipher	String	否		秘钥加密后的密文 如开启数据加密则此字段必传
options.media_size	String	否	KIC_MS_A4	介质尺寸 参见 获取打印机能力接口 和 参数常量
options.media_type	String	否	KIC_MT_PLAIN	介质类型 参见 获取打印机能力接口 和 参数常量
options.color_mode	String	否		色彩模式 参见 获取打印机能力接口 和 参数常量
options.borderless	Bool	否	false	是否开启无边距打印 参见 获取打印机能力接口
options.quality	String	否		打印质量 参见 获取打印机能力接口 和 参数常量
options.duplex	String	否		双面打印模式 参见 获取打印机能力接口 和 参数常量
options.input_slot	String	否		进纸器模式 参见 获取打印机能力接口 和 参数常量
options.number	Integer	否	1	打印份数 详见 打印顺序说明
options.page_ranges	String	否		打印范围（如：1,3,5 1-10 1-3,5,6-10 ）
options.reverse	Bool	否	true	是否倒序打印 详见 打印顺序说明 （如打印机出纸时正面朝下，关闭倒序打印可以按正确的顺序打印）
options.collate	Bool	否	true	是否逐份打印 详见 打印顺序说明 详见 打印顺序说明

• 响应参数（JSON Body）:

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

• 成功示例：

HTTP Status 200

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

• 失败示例：

HTTP Status 200

{
  "code": 30301,
  "msg": "打印机未连接",
  "data": null
}

查看全部状态码

主动取消打印接口 API

提示

取消打印会取消终端当前已接收和正在打印的打印任务，并清空打印队列

POST /api/print/cancel

• 请求参数（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/print/info

• 请求参数（JSON Body）：

名称	类型	必选	说明
client_uuid	String	是	设备UUID
print_uuid	String	是	打印任务UUID

• 响应参数（JSON Body）:

名称	类型	必选	说明
code	Integer	是	状态码
msg	String	是	状态描述
data	Object	否	响应数据
data.action_ack	Bool	否	终端是否已接收
data.action_ack_at	Integer	否	终端接收时的Unix时间戳（单位：毫秒）
data.started	Bool	否	打印开始是否已开始
data.started_at	Integer	否	打印开始时的Unix时间戳（单位：毫秒）
data.finished	Bool	否	是否已结束打印
data.finished_at	Integer	否	结束打印时的Unix时间戳（单位：毫秒）
data.file_size	Integer	否	文件大小（单位：KB）
data.download_spent	Integer	否	终端下载文件耗时（单位：秒）
data.error_code	Integer	否	打印错误码，详见 打印错误码
data.created_at	Integer	否	打印任务创建时的Unix时间戳（单位：毫秒）
data.expires_at	Integer	否	此次打印任务的过期时间（Unix时间戳，单位：秒。 达到过期时间之后，打印任务会自动销毁，任务信息无法查询，一般为24小时之后 ）
data.pages	Integer	否	预估页数 （根据文件与份数设置的评估值，非实际打印页数，在打印开始时有值）
data.printed_pages	Integer	否	使用严格模式时的实际打印面数 （只有在严格模式打印结束时有值） 注意：此值为打印面数，如打印的文档页数为3页并启用双面打印模式，此时值为4 （空白面也会计算，当启用双面打印时，printed_pages/2 即可得到实际使用的纸张数量）

• 成功示例：

HTTP Status 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "action_ack": true,
    "action_ack_at": 1632366541630,
    "created_at": 1632366540940,
    "download_spent": 1,
    "error_code": 0,
    "expires_at": 1632452940,
    "file_size": 588,
    "finished": true,
    "finished_at": 1632366673254,
    "pages": 9,
    "printed_pages": 9,
    "started": true,
    "started_at": 1632366544625
  }
}

查看全部状态码