OpenAPI

云打印开放平台 API 接口文档

接入指南
底层方法
使用协议
打印机选型
创建打印任务
查询打印任务
取消打印任务
打印任务回调
打印状态回调

开始使用 - 入门指南

UV云打印开放平台是由瑞丰彩® 团队自主设计和研发的SAAS软件系统，专业可靠。
UV云打印开放平台基于互联网云服务、云存储和瑞丰彩® UV打印机硬件，借助即时通讯、数据交互、开放互联等互联网技术，提供互联网与UV打印机资源相结合的打印服务，让开发者的第三方平台可以通过网络请求的方式实现与UV打印机进行实时通信，实现远程调用和打印的功能。

UV云打印开放平台由开放平台、瑞丰彩® 网络打印接口、打印终端软件、打印驱动软件组成，通过整合的方式形成接口对外开放，让开发者可以轻松对接瑞丰彩云® 打印，快速实现各类自定义的打印需要与服务。

若设备在调试过程中遇到不能解决问题，可以联系云打印负责人排除问题，找到解决的方法。联系方法如下：
电 话：137-5177-4454【微信同号】
邮 箱：info@ColorPark.cn
开放平台新手引导
开通账号
登录开放平台
请求接口
接口适用与面向场景
调用平台提供的打印接口，打印机配合云端服务、客户端应用，实现任务调度，排队打印。
同时，可实时查阅任务状态，设备状态，还可以对设备进行远程清洗维护等。

适用场景：有联网需求的各类Web应用、小程序、APP
基本概念与技术术语
1、设备编号
每台打印机都会分配一个唯一的设备编号，在“设备列表”中可以查看和复制设备编号。
2、设备密钥
设备密钥是企业应用里面用于保障数据安全的“钥匙”，每一个应用都有一个独立的访问密钥，为了保证数据的安全，设备密钥务必不能泄漏。
3、生成签名
生成签名是通过设备编号、设备密钥、随机数、生成时间经过加密后生成一个加密字符串，用于在传输时验证对方来源数据的真实性。签名的生成方式请参加《生成签名》章节。
4、回调接口
回调接口是瑞丰彩开放平台通知第三方平台的途径，比如打印机的状态，打印任务的进度都是通过回调的方式通知第三方平台，具体请参考《打印机状态回调》与《打印任务回调》章节。
5、打印终端软件
打印终端软件是一个用来接收打印交互消息、接收打印图片、打印图片处理与传入打印机的软件，它连接开放平台和打印机的中间软件，每一台打印机的连接的电脑，必须安装一个打印终端软件，并绑定对应的设备编号。

结语

只需专注   业务场景

选择 ColorPark UV云打印 - 免去研发投入，免去服务器投入，免去繁琐操作

底层方法【基础支撑】

一、基础支撑
在真实使用环境中，需要经过以下步骤才能真正实现第三方平台与瑞丰彩网络打印接口的调用，完成整套的自定义UV打印服务。
1、购买瑞丰彩的UV打印机
2、安装打印机驱动软件
3、安装打印终端软件
4、在打印终端软件上绑定分配的设备编号
5、实现与网络打印接口的对接
二、生成签名（底层方法）
生成的签名是用于验证接口请求合法性的关键参数，具有以下作用：
1、防止请求被篡改：签名的生成需要使用secret等密钥，只有知道这些密钥的人才能生成正确的签名，这样可以防止请求被篡改或者恶意攻击。
2、防止重放攻击：签名中包含了时间戳（time）等参数，每个请求的签名都是不同的，这样可以防止同一个请求被重复发送，防止重放攻击。
3、确认请求来源：签名中包含了开发者的printer_id等参数，可以用来确认请求的来源，防止非法请求。
因此，在开放平台的接口开发中，验证签名是非常重要的一步。开发者需要根据瑞丰彩开放平台提供的签名算法，在接收到请求后验证签名的正确性，确保接口请求的合法性。只有通过签名验证的请求才能继续进行后续的业务处理。
三、生成签名的具体方法
1、参与签名的字段包括设备编号（printer_id）、设备密钥（key）、once(随机字符串，由开发者随机生成)、time（当前的生成时间，由开发者生成）
2、对所有待签名参数按照字段名的 ASCII 码从小到大排序（字典序）后，使用 URL 键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1。这里需要注意的是所有参数名均为小写字符

特别注意以下重要规则：
1）. 参数名ASCII码从小到大排序（字典序）。
2）. 如果参数的值为空不参与签名。
3）. 参数名区分大小写。

3、接下来对 string1 作 md5 加密

结语

物不在多，有用则精。

ColorPark - 我们拥有一支卓越，创新的软硬件研发设计团队

云打印开放平台 API 调用协议

1.概述
云打印开放平台通讯协议是一个无状态的、轻量级的基于HTTP的 RPC 通讯协议
2.安全说明
出于用户体验考虑，同时为了平衡兼容和安全风险，接口网关侧支持https，入驻用户请使用https 协议。
3.设计原则
本协议只定义数据交互的格式与方式，不关注数据的传输方式，不关注认证方式，不关注接口版本控制。
4.RPC 调用
开放平台的 RPC 调用主要用于客户端应用主动获取开放平台服务器端数据信息，是通过客户端应用向开放平台的API服务器发送HTTP POST或GET请求对象，而服务器返回响应对象实现的。
如无特殊说明，接口的所有参数值均为 UTF-8 编码

打印机选型

带有网络功能的打印机都能升级对接云打印功能，且打印产品不受限制。
型号 图片 参数
PC 适用：UV
喷头：单喷头
高度：固定
配色：CMYK / CMYK+W
尺寸：60*47*42.5 cm
重量：33kg
TS1/2 适用：UV/ 纺织 / 光油
喷头：单喷头 / 双喷头
高度：5CM
配色：CMYK / CMYKW / CMYKW 光油
尺寸：80.5*76.5*51 cm
重量：60kg
ZZ1E/2E 适用：UV / 纺织 / 食品 / 光油
喷头：单喷头 / 双喷头
高度：20CM
配色：CMYK /CMYKW / CMYKW 光油
尺寸：80*76.5*63.5cm
重量：72kg

创建打印任务

创建打印任务，主要用于第三方平台通过接口的方法往开放平台发送打印的图片任务，开放平台接收到打印任务后，会自动派发到对应的设备编号的打印终端软件上。派发打印任务可以离线派发，打印终端上线后就能接收到所有的离线的派发任务。
一、接口信息
接口地址 https://www.colorpark.cn/api/Printer/mulPrint
请求方式 POST
二、请求参数
参数名 参数值（示例） 必须 参数说明
printer_id 500001 是 打印机分配的唯一ID号，每一台打印都会分配一个不同的编号
once 8305 是 加密生成签名时使用的随机数值
time 1646790335 是 加密生成签名时使用的时间戳
sign 9ce3ce7a3fccaf3d7715bd7e9bb1dc1c 是 生成的签名，生成方式请参考《底层方法【基础支撑】》生成签名 章节
order_id 164679033555822 是 第三方平台的订单编号,由第三方平台生成，最大接受32位字符
name 商品A 是 第三方平台的商品名称,由第三方平台生成，最大接受32位字符
file https://img.colorpark.cn/api/render/36531651306594235.png 是 需要打印的图片网址，图片就第三方平台生成，网址最大接受255位字符
width 185 否 打印的图片宽度，单位为mm
height 140 否 打印的图片高度，单位为mm
left 0 否 打印起点的左边距，单位为mm
top 0 否 打印起点的上边距，单位为mm
callback http://www.abc.com/api/callback 是 第三方系统用于接收打印通知的回调地址，如开始打印通知、完成打印通知、取消打印通知、打印故障通知
三、返回结果
参数名 参数值(示例) 参数说明
code 0 返回结果状态码，成功时为0，失败时为1
msg 提交成功 返回结果描述，如：提交成功
data taskid 20000196 打印任务的唯一编号
order_id 164679033555822 第三方平台的订单编号,由第三方平台生成，最大接受32位字符
status 0 打印任务状态，0:等待打印 1:正在打印 2:完成打印 3:取消打印 4:打印故障

查询打印任务

查询打印务主要用于查询已经派发的打印任务的主要信息，可以在第三方平台需要展示打印任务信息的地方调用。
一、接口信息
接口地址 https://www.colorpark.cn/api/Printer/getTask
请求方式 POST
二、请求参数
参数名 参数值（示例） 必须 参数说明
printer_id 500001 是 打印机分配的唯一ID号，每一台打印都会分配一个不同的编号
once 8305 是 加密生成签名时使用的随机数值
time 1646790335 是 加密生成签名时使用的时间戳
sign 9ce3ce7a3fccaf3d7715bd7e9bb1dc1c 是 生成的签名，生成方式请参考《底层方法【基础支撑】》生成签名 章节
taskid 20000196 是 打印任务的唯一编号
三、返回结果
参数名 参数值（示例） 参数说明
code 0 返回结果状态码，成功时为0，失败时为1
msg 提交成功 返回结果描述，如：提交成功
data taskid 20000196 打印任务的唯一编号
printer_id 500001 打印机唯一编号
order_id 164679033555822 第三方平台的订单编号,由第三方平台生成，最大接受32位字符
template_id 1 打印模板编号
name 商品A 商品名称
file https://img.colorpark.cn/api/render/80301001651287933588.png 打印图片的URL地址
status 0 打印任务状态，0:等待打印 1:正在打印 2:完成打印 3:取消打印 4:打印故障
callback 0 第三方系统用于接收打印通知的回调地址，如开始打印通知、完成打印通知、取消打印通知、打印故障通知
create_time 0 打印任务创建的时间
start_time 0 打印任务开始打印的时间
finish_time 0 打印任务完成打印的时间

取消打印任务

如果在派发打印任务后，又不需要对打印任务进行打印了，比如订单已经退款时，就可以在第三方平台对开放平台发现取消打印任务的调用，如果打印任务正在打印中或者已经打印完成，打印任务则无法再成功取消。
一、接口信息
接口地址 https://www.colorpark.cn/api/Printer/cancelPrint
请求方式 POST
二、请求参数
参数名 参数值（示例） 必须 参数说明
printer_id 500001 是 打印机分配的唯一ID号，每一台打印都会分配一个不同的编号
once 8305 是 加密生成签名时使用的随机数值
time 1646790335 是 加密生成签名时使用的时间戳
sign 9ce3ce7a3fccaf3d7715bd7e9bb1dc1c 是 生成的签名，生成方式请参考《底层方法【基础支撑】》生成签名 章节
taskid 20000196 是 打印任务的唯一编号
三、返回结果
参数名 参数值(示例) 参数说明
code 0 返回结果状态码，成功时为0，失败时为1
msg 提交成功 返回结果描述，如：提交成功
data taskid 20000196 打印任务的唯一编号
printer_id 500001 打印机唯一编号
order_id 164679033555822 第三方平台的订单编号,由第三方平台生成，最大接受32位字符
status 3 打印任务状态，3:取消打印

打印任务回调

该接口由第三方平台开发，开放平台往该接口传送打印任务实时消息，第三方平台需要对不同的消息进行处理，比如正在打印，打印完成，打印取消，打印故障。第三方平台可以对消息根据不同的状态进行对应的处理。
一、回调接口信息
接口地址 http://xxxx.com/api/callback
请求方式 POST
二、回调参数
参数名 参数值（示例） 参数说明
taskid 20000196 打印任务的唯一编号
printer_id 500001 打印机分配的唯一ID号，每一台打印都会分配一个不同的编号
order_id 20000196 第三方系统中的订单编号
status 2 打印任务状态   1:正在打印 2:完成打印 3:取消打印 4:打印故障
msg 完成打印 根据任务status显示不同信息。  1:正在打印 2:完成打印 3:取消打印 4:打印故障
三、第三方平台返回
回调处理说明 第三方收到返回消息后，处理完成需要输出确认信息，如不输出处理结果信息或者处理结果为fail，回调将在2小时内将5重复提交到回调接口，2小时后将放弃处理
回调处理成功返回字符串 success
回调处理失败返回字符串 fail

打印机状态回调

该接口由第三方平台开发，开放平台往该接口传送打印机的状态，比如打印软件离线，在线空闲，打印中，故障。第三方平台可以对消息根据不同的状态进行对应的处理。
一、回调接口信息
接口地址 http://xxxx.com/api/printerStatus
请求方式 POST
说明 该接口由第三方平台开发，开放平台往该接口传送打印实时消息，第三方平台需要对不同的消息进行处理
二、回调参数
参数名 参数值（示例） 参数说明
printer_id 500001 打印机分配的唯一ID号，每一台打印都会分配一个不同的编号打印机状态回调功能
status 2 打印机状态，0:离线 1:空闲 2:打印中 3:故障
msg 完成打印 根据打印机状态显示不同信息 0:离线 1:空闲 2:打印中 3:故障
notice_time 2022-07-19 17:08:30 通知时间
三、第三方平台返回
回调处理说明 第三方收到返回消息后，处理完成需要输出确认信息，如不输出处理结果信息或者处理结果为fail
回调处理成功返回字符串 success
回调处理失败返回字符串 fail