云打印 API 接口文档_HTTP/MQTT 对接

快速开始

5分钟完成首次打印

按照以下步骤，快速验证云打印功能：

获取账号：登录 sw-aiot.com 注册用户账号
绑定设备：使用设备底标的机器码和验证码，通过"设备绑定"接口完成绑定
在线调试：点击任意API的"接口调试"按钮，在线模拟调用
打印测试：调用"文本打印任务推送"接口，发送测试内容

快速接入

标准HTTP/HTTPS接口，30分钟完成业务集成

在线调试

每个API都提供在线调试功能，实时查看请求和响应参数

选择鉴权方式（请先二选一）

两套接口路径不同，请勿混用。按业务场景选择后，按对应调试页顺序验证：

对比项	固定验签	定期刷新 Token
适用场景	服务端直连，无需频繁刷新	多端调用，先取 Token 再请求
API 前缀	`/api/printer/*`	`/api/device/`、`/api/message/`
鉴权方式	Header token = MD5(secret&times&username)；Body 含 username、times	先调 getToken，再在 Header 带返回的 token
推荐调试顺序	绑定 → 打印	取 Token → 绑定 → 打印

标签排版与可视化编辑

设计标签可直接使用在线打标签；完整 JSON 字段说明见基于 JSON 标签排版。

协议定义

云打印API接口，为应用提供统一、可靠、安全的云打印服务及设备管理。一次对接，多机型通用。

支持的打印机类型

热敏票据、标签打印机（含58mm、80mm、110mm宽度的标签及票据打印机）
热转印打印机
针式打印机
智能打印云盒

协议规范

使用HTTP/HTTPS协议，确保数据传输安全
支持基于动态token(最长120分钟刷新时间)的接口访问，或固定验签的接口访问

打印内容排版

独创基于JSON的票据\标签排版打印语言，无需熟悉ESC/POS、TSPL指令，支持png等图片内嵌打印
基于XML的智能排版语言，支持全球语言打印，丰富的智能排版功能，如带边框的表格等复杂排版
兼容市面其他厂商常用的简易XML排版
同时支持ESC/POS、TSPL指令，可根据打印机型号选择合适的指令集

设备本地配网协议（蓝牙 BLE）

基于标准 GATT 的写 / 读两种操作，完成 WiFi 配网、静态 IP 设置与联网状态查询，无需厂商私有 SDK
适用于手机 App、微信小程序、桌面配网工具等宿主应用，自行集成完整配网流程
与上述云端 API 互补：本协议负责把设备接入网络，云端 API 负责任务下发与设备管理

查看蓝牙 BLE 配网协议 →

API接口

固定验签的接口

固定验签接口不需要通过API接口获取Token。该接口采用静态签名方式，每次请求都需要计算签名。

通用规则：

API接口地址前缀：https://open.sw-aiot.com/api/printer/
方法：POST
Content-Type：application/json
请求头：
token: md5(secret=xxx&times=xxxx&username=xxxx)
注：计算结果为32位值，不区分大小写。

必填请求参数(与header中的参与token计算的参数username、times保持一致)：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名
times	时间戳	Long	是	13位毫秒级时间戳，必须与请求头token中的times保持一致

设备绑定接口调试

URL：https://open.sw-aiot.com/api/printer/bindPrint

方法：POST

Content-Type：application/json

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名
times	时间戳	Long	是	13位毫秒级时间戳
devid	设备编号	String	是	设备机器码
key	校验码	String	是	设备校验码
nickname	设备名称	String	否	设备别名
timeout	超时时间	Integer	否	消息保留时间(秒)，建议1800
pwidth	纸张宽度	Integer	否	单位 mm。例：58、80、104、203
pheight	打印高度	Integer	否	单位 mm（针式打印建议填写）
ptype	纸张类型	Integer	否	打印任务未传 ptype 时默认取此值。 1. 连续纸 2. 标签纸 3. 黑标纸 4. 穿孔纸

请求示例：

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "key": "4463",
    "nickname": "测试设备",
    "timeout": 1800,
    "pwidth": 58,
    "pheight": 30,
    "ptype": 2
}

设备解绑接口调试

URL：https://open.sw-aiot.com/api/printer/unBindPrint

方法：POST

Content-Type：application/json

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名
times	时间戳	Long	是	13位毫秒级时间戳
devid	设备编号	String	是	设备机器码
key	校验码	String	是	设备校验码

请求示例：

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "key": "4463"
}

文本打印任务推送接口调试

URL：https://open.sw-aiot.com/api/printer/printMsg

方法：POST

Content-Type：application/json

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名
times	时间戳	Long	是	13位毫秒级时间戳
devid	设备编号	String	是	设备机器码
reqid	请求ID	String	是	唯一请求标识，用于追踪任务
message	打印内容	String	是	可为排版文本/JSON/XML 内容，或文件下载链接。 type 为 1/6/7 时请传入数据文件下载地址（含 PDF 链接），服务器会自动识别
type	任务类型	Integer	是	1. ESC 2. CPCL 3. TSPL 4. XML 打印排版设计 5. JSON 打印排版设计 6. IMG（支持 png；可传图片下载链接） 7. PDF（传 PDF 文件下载链接） 99. 设备配置
pcopy	打印份数	Integer	否	默认值 1
pwidth	纸张宽度	Integer	否	单位 mm。例：58、80、104 （打印云盒建议填写）
pheight	打印高度	Integer	否	单位 mm。针式打印建议填写
ptype	纸张类型	Integer	否	如无此参数，默认为绑定时填写的类型。 1. 连续纸 2. 标签纸 3. 黑标纸 4. 穿孔纸
vtype	音频类型	Integer	否	-1:不播报 0:定制语音大于等于1:播报指定编号语音*
vmessage	TTS语音播报内容	String	否	最多60个字符

请求示例：

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "reqid": "e970e65af9bd4dfb9400d896607bc812",
    "message": "打印文本内容...",
    "type": 1,
    "pcopy": 1,
    "pwidth": 80,
    "pheight": 100,
    "ptype": 1,
    "vtype": -1
}

文件打印任务推送接口调试

接口说明：

本接口用于上传文件进行打印（固定验签方式）。参数说明与「定期刷新 token」中的文件打印任务推送一致，另需携带 username、times，并使用固定验签计算 Header token。

本接口为异步接口，返回200表示服务器成功接收任务并加入队列，不代表打印成功。打印结果需要通过注册回调接收异步通知。

URL：https://open.sw-aiot.com/files/ptFile

方法：POST

Content-Type：multipart/form-data

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名（与固定验签文本打印一致）
times	时间戳	Long	是	13位毫秒级时间戳（参与 token 计算，需与 Header 一致）
devid	机器码	String	是	设备机器码
file	上传的文件	file	是	type=9 且传入 url 时可省略
url	动态网页 URL	String	否	type=9 时可传网页链接，此时可不传 file
reqid	请求ID	String	是	唯一请求标识，用于追踪任务
type	内容类型	Integer	是	1:ESC 6:IMG 7:PDF 8:WORD 9:HTML
width	有效打印宽度	Integer	否	单位 mm。如 58mm 机有效宽约 48；80→72；110→104；针打等分约 210
height	纸张高度	Integer	否	单位 mm。针打场景建议填写
pcopy	打印份数	Integer	否	默认值 1
ptype	纸张类型	Integer	否	如无此参数，默认为绑定时填写的类型。 1. 连续纸 2. 标签纸 3. 黑标纸 4. 穿孔纸
rotate	旋转	Integer	否	0不旋转；1/2/3 顺时针每次90°；4水平镜像；5垂直镜像

请求示例：

POST https://open.sw-aiot.com/files/ptFile?devid=SW214800001&type=6&width=72&height=100&pcopy=1&ptype=2&reqid=e970e65af9bd4dfb9400d896607bc812&username=your_username&times=1683916200000
Header: token = md5(secret=xxx&times=1683916200000&username=your_username)
Body (multipart/form-data): file=@label.png

注：type=9 的 HTML 打印可传动态网页 url，此时可不传 file：
...&type=9&url=https://example.com/print.html&pcopy=1&ptype=2&username=your_username&times=1683916200000

语音播报消息推送接口调试

URL：https://open.sw-aiot.com/api/printer/voiceMsg

方法：POST

Content-Type：application/json

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名
times	时间戳	Long	是	13位毫秒级时间戳
devid	设备编号	String	是	设备机器码
reqid	请求ID	String	是	唯一请求标识，用于追踪任务
vmessage	语音内容	String	是	语音播报文本内容
vtype	音频类型	Integer	是	语音播报类型

请求示例：

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "reqid": "e970e65af9bd4dfb9400d896607bc812",
    "vmessage": "您有新的订单，请注意查收",
    "vtype": 0
}

设备信息查询

接口说明：

本接口用于获取设备信息。

URL：https://open.sw-aiot.com/api/printer/getDevice/{devid}

方法：GET

Content-Type：application/json

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

注：devid 为 URL 路径参数，username、times 为 URL 查询参数，且参与请求头 token 计算。

参数名	字段描述	类型	必须	说明
devid	机器码	String	是	设备ID（URL路径参数）
username	用户名	String	是	开发者账号用户名（URL 查询参数）
times	时间戳	Long	是	13位毫秒级时间戳（URL 查询参数）

请求示例：

https://open.sw-aiot.com/api/printer/getDevice/SW1234567890?username=your_username&times=1683916200000

返回参数：

返回参数字段	字段描述	类型
code	应答码：200成功，非200则失败	int
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	设备信息	Json

返回示例：

{
    "code": 200,
    "message": "操作成功",
    "success": true,
    "data": {
        "devid":"SW1234567890",
        "state":"online",
        "status":1,
        "createdate":"2021-05-16 12:12:12"
    }
}

待打印任务队列清空接口调试

接口说明：

本接口用于通过机器码清空等待队列的任务数据。

URL：https://open.sw-aiot.com/api/printer/clear

方法：POST

Content-Type：application/json

请求头：token = md5(secret=xxx&times=xxxx&username=xxxx)

请求参数：

参数名	字段描述	类型	必须	说明
username	用户名	String	是	开发者账号用户名
times	时间戳	Long	是	13位毫秒级时间戳
devid	机器码	String	是	设备机器码

请求示例：

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890"
}

返回说明：

清空成功,返回true

定期刷新token的接口

登录授权，获取token 接口调试

本接口为应用获取接口访问权限的token。token有效期为120分钟，超时则token失效；重新获取token原token立即失效。

建议应用刷新token频率30-60分钟一次。token每天最多可获取不超过240次，请勿频繁刷新token。

URL： https://open.sw-aiot.com/api/getToken

方法： POST

Content-Type： application/json

请求参数：

参数名	字段描述	类型	必须	说明
username	登录名	String	是	用户注册时填写的用户名，可在开发者中心查看
password	密码	String	是	由多个字段组合生成，密码生成方法见如下"password参数生成说明"
times	时间戳	Long	是	13位毫秒级时间戳，服务器会对比当前时间，请保持此参数值与password中的times一致

password参数生成说明

1.参数排序及拼接

如下表格中参数按照参数名ascii码从小到大排序，使用URL键值对的格式，拼接成待签名字符串

password生成参数（参数均不可为空）

参数名称	参数描述
username	注册用户名
secret	开发者中心查看secret（获取到secret后，存入服务器避免对外泄露）
times	请求的网络时间戳(13位)，请使用即时时间(服务器会用当前时间进行比对，时间相差过超5分钟则拒绝请求)

secret=secret001&times=16788909829382&username=sw-aiot

2. MD5生成password

对拼接好的签名参数，进行MD5加密，把MD5结果字符串转大写，即为password参数值

password生成示例

假设参数为：username=sw-aiot, secret=secret001, times=16788909829382

1. 按ascii码排序后拼接：secret=secret001&times=16788909829382&username=sw-aiot

2. 进行MD5加密并转大写：password = MD5("secret=secret001&times=16788909829382&username=sw-aiot").toUpperCase()

请求示例：

{
   "username": "sw-aiot",
   "password": "5F52EC78A3B496D9FA8C5E3A74FE520B",
   "times": 16788909829382
}

返回参数：

Content-Type: application/json

参数名称	字段描述	类型
code	应答码	String
message	应答信息	String
success	请求成功标志	Boolean
data	响应数据内容	json
token	用户权鉴token	String

返回示例：

{
    "code": 200,
    "message": "获取成功",
    "success": true,
    "data": {
        "token": "dsfqewt1asd13464573reasdf243"
    }
}

设备绑定接口调试

用于设备绑定，只需要绑定一次；绑定后如果需要更换绑定账号，请先参考《设备解绑》进行设备解绑（只有绑定的应用方才有权限解绑，也可通过开发者中心设备管理界面进行绑定或解绑）

URL： https://open.sw-aiot.com/api/device/bindPrint

方法： POST

Content-Type： application/json

请求头：

token=xxxxxxxxx

请求参数：

参数字段	字段描述	类型	必须	说明
devid	机器码	String	是	设备ID
key	校验码	String	是	设备验证密钥
timeout	设备消息保留时间	int	否	设备故障修复后，设备将继续打印该时间内的消息，单位：s。建议设置120s以上，不超过1周604800s
pwidth	纸张宽度	int	否	单位 mm。例：58、80、104、203
pheight	打印高度	int	否	mm
ptype	纸张类型	int	否	打印任务未传 ptype 时默认取此值。 1. 连续纸 2. 标签纸 3. 黑标纸 4. 穿孔纸
nickname	设备名称	String	否	请使用文字、字母、_组合，不要使用其他特殊字符

请求示例：

{
    "devid": "SW1234567890",
    "key": "4463",
    "timeout": 200,
    "pwidth": 58,
    "ptype": 2,
    "nickname": "商为集团_商为科技中心"
}

返回参数：

Content-Type: application/json

参数字段	字段描述	类型
code	应答码：200成功，非200则失败	int
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	响应数据内容	Json

返回示例：

{
    "code": 200,
    "message": "操作成功",
    "success": true,
    "data": {}
}

设备解绑接口调试

已绑定的设备解绑。

只有绑定该设备的应用方才可执行解绑操作。

URL： https://open.sw-aiot.com/api/device/unBindPrint

方法： POST

Content-Type： application/json

请求头：

token=xxxxxxxxx

请求参数：

参数字段	字段描述	类型	必须
devid	机器码	String	是
key	设备校验码	String	是

请求示例：

{
    "devid": "SW1234567890",
    "key": "4463"
}

返回参数：

Content-Type: application/json

参数字段	字段描述	类型
code	应答码：200成功，非200则失败	int
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	响应数据内容	Json

返回示例：

{
    "code": 200,
    "message": "操作成功",
    "success": true,
    "data": {}
}

文本打印任务推送接口调试

向指定机器码的云打印设备推送文本字符串类型打印数据。

本接口为异步接口，返回200表示服务器成功接收任务并加入队列，不代表打印成功。打印结果需要通过注册回调接收异步通知。

URL： https://open.sw-aiot.com/api/message/printMsg

方法： POST

Content-Type： application/json

请求头：

token=xxxxxxxxx

请求参数：

参数字段	字段描述	类型	必须
devid	机器码	String	是
reqid	请求标识，用于标记当前请求	String	是
message	打印内容注：按照标准排版内容格式，XML/JSON格式详细参照《排版约定》。此内容可以是打印内容或内容下载地址 type为1/6/7请传入数据文件下载地址（含 PDF 链接；或通过《文件打印任务推送》接口实现打印），服务器会自动识别 type为99时，message 为设备配置内容	String	是
type	内容类型:（如不填或类型与内容不匹配，则不打印） 1. ESC 2. CPCL 3. TSPL 4. XML 打印排版设计 5. JSON 打印排版设计 6. IMG（支持png格式图片；可传图片下载链接） 7. PDF（传 PDF 文件下载链接） 99. 设备配置	int	是
pcopy	打印份数，默认值 1	int	否
pwidth	纸张宽度：mm。例：58、80、104 （打印云盒此参数必填）	int	否
pheight	打印高度（针式打印必填）	int	否
ptype	打印纸张类型。如无此参数，默认为绑定时填写的类型。 1. 连续纸 2. 标签纸 3. 黑标纸 4. 穿孔纸	int	否
vtype	语音类型: -1:无播报 0:定制语音大于等于1:播报指定编号语音*	int	是
vmessage	vType为0时，推送定制语音内容;不为0时，此字段内容自动失效注：语音使用和收费规则，详见《附录C-定制语音描述》	String	否

请求示例：

{
"devid": "SW1234567890",
"reqid": "e970e65af9bd4dfb9400d896607bc812",
"message": "打印文本内容...",
"type": 1,
"pcopy": 1,
"pwidth": 80,
"pheight": 100,
"ptype": 1,
"orderid": "30220191208161723852129466170919",
"vtype": -1,
"vmessage": "测试语音订单"
}

返回参数：

参数字段	字段描述	类型
code	应答码：200成功，非200则失败	int
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	响应数据内容	Json
code	接口信息编码参照《附录A》	string
message	错误信息描述	String
reqid	任务编号	String
success	是否成功（true--消息已发送设备或存档，不需要重推；false--入库失败，需要重新推送）其他描述字段，只做参考	boolean

返回示例：

{
"code": 200,
"message": "操作成功",
"success": true,
"data": {
    "message":"Device is failure!",
    "reqid":"123456789",
    "success":true,
    "code":"101"
} --如推送成功，此处无数据，推送失败，此处为失败原因描述
}

文件打印任务推送

接口说明：

本接口用于上传文件进行打印

本接口为异步接口，返回200表示服务器成功接收任务并加入队列，不代表打印成功。打印结果需要通过注册回调接收异步通知。

URL： https://open.sw-aiot.com/files/ptFile

方法： POST

Content-Type： multipart/form-data

请求头：

token=xxxxxxxxx

请求参数：

参数字段	字段描述	类型	必须
devid	机器码	String	是
file	上传的文件	file	是
url	type=9时，可传动态网页的URL连接，包含此参数，则file参数不传	String	否
reqid	请求标识，用于标记当前请求	String	是
type	内容类型:（如果不填或类型不对，则内容直接丢弃不打印） 1. ESC 6. IMG 7. PDF 8. WORD 9. HTML	int	是
width	注：图片、PDF、Word、HTML打印需要传入对应打印机有效打印宽度，如58mm打印机有效打印宽度为48mm，对应384个点 80mm有效打印宽度为72mm，对应576个点 110mm有效打印宽度为104mm，对应832个点针打一二三等分有效打印宽度为210mm	int	是
height	纸张高度：mm。例：93/139.5/279 注：打印云盒此参数必填。	int	否
pcopy	打印份数，默认值 1	int	否
ptype	打印纸张类型。如无此参数，默认为绑定时填写的类型。 1. 连续纸 2. 标签纸 3. 黑标纸 4. 穿孔纸	int	否
rotate	旋转次数。顺时针旋转次数（每次90°。参数值为0/1/2/3/4/5，超出指定值，不旋转） 0-不旋转 1-顺时针旋转1次 2-顺时针旋转2次 3-顺时针旋转3次 4-水平翻转(镜像) 5-垂直翻转(镜像)	int	否

请求示例：

http://file.sw-aiot.com/files/ptFile?devid=SW214800001&type=1&width=80&height=100&pcopy=1&ptype=2&rotate=3

注：type=9 的html打印，支持传入动态网页url链接，对应请求示例如下：
http://file.sw-aiot.com/files/ptFile?devid=SW234900050&type=9&reqid=8963202312250652301151&width=210&height=139&pcopy=1&ptype=2&url=xxxx
其中xxx 为打印目标网页的链接

返回参数：

参数字段	字段描述	类型
code	应答码：200成功，非200则失败	int
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	响应数据内容	Json
code	接口信息编码参照《附录A》	String
message	错误信息描述	String
reqId	任务编号	String
success	是否成功（true--消息已发送设备或存档，不需要重推；false--入库失败，需要重新推送）其他描述字段，只做参考	Boolean

返回示例：

{
"code": 200,
"message": "操作成功",
"success": true,
"data": {
    "message": "Device is failure!",
    "reqId": "123456789",
    "success": true,
    "code": "101"
}
}

语音播报消息推送

接口说明：

本接口用于向指定机器码的设备推送播报内容。

URL： https://open.sw-aiot.com/api/message/voiceMsg

方法： POST

Content-Type： application/json

Header： token=xxxxxxxxx

请求参数：

参数名称	字段描述	类型	必须
devid	机器码	String	是
reqid	请求标识，用于标记当前请求	String	是
orderid	交易流水号	String	否
vmessage	播报内容注：定制语音使用和收费规则，详见《附录C》	String	是
vtype	播报类型: 0、定制语音; 1、你有新的外卖订单，请及时处理; 2、你有新的美团订单，请及时处理; 3、你有新的饿了么订单，请及时处理。	int	是

请求示例：

{
"devid": "SW1234567890",
"reqid": "e970e65af9bd4dfb9400d896607bc812",
"vmessage": "黔农E付微信收款123.45元",
"vtype": 0,
"orderid": "30220191208161723852129466170919"
}

返回参数：

参数名称	字段描述	类型
code	应答码：200成功，非200则失败	String
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	响应数据内容	Json

返回示例：

{
"code": 200,
"message": "操作成功",
"success": true,
"data": {}
}

设备信息查询

接口说明：

本接口用于获取设备信息。

URL： https://open.sw-aiot.com/api/device/getDevice/{devid}

方法： GET

Content-Type： application/json

请求头：

token=xxxxxxxxx

请求参数：

参数字段	字段描述	类型	必须
devid	机器码	String	是

请求示例：

https://open.sw-aiot.com/api/device/getDevice/SW1234567890

返回参数：

返回参数字段	字段描述	类型
code	应答码：200成功，非200则失败	int
message	应答信息，应答码对应的描述	String
success	请求成功标志	Boolean
data	设备信息	Json
devid	机器码	String
nickname	设备备注名称	String
typename	设备类型	String
iccid	ICCID	String
remark	设备描述	String
state	设备在线状态。编码参考附录A-1编码对照表	String
status	设备故障状态。编码参考附录A-2编码对照表	String
taskcnt	任务堆积数量	int
version	设备固件版本号	String
createdate	设备注册时间	datetime

返回示例：

{
"code": 200,
"message": "操作成功",
"success": true,
"data": {
    "devid":"SW1234567890",
    "state":"online",
    "status":1,
    "createdate":"2021-05-16 12:12:12"
}
}

待打印任务队列清空接口调试

接口说明：

本接口用于通过机器码清空等待队列的任务数据。

URL： https://open.sw-aiot.com/api/message/clear

方法： POST

Content-Type： application/json

请求头：

token=xxxxxxxxx

请求参数：

参数字段	字段描述	类型	必须
devid	机器码	String	是

请求示例：

{
    "devid": "SW1234567890"
}

返回说明：

清空成功,返回true

设备状态及打印结果回调

本文档用于描述数据处理回调功能，包含打印结果回调、设备在线状态变更回调、设备故障状态回调。

接口地址为三方应用提供的接口地址，厂方服务器以固定参数形式推送通知内容。

回调接口在线验证：登记回调地址后，可用回调接口在线验证工具模拟平台调用，验证联通性与返回格式（POST + application/json，期望返回 {"message":"OK"}）。

设备状态/任务结果回调

通知方式：HTTP 或 MQTT（二选一，在开发者中心 - 回调地址中设置通知类型：1 - HTTP / 2 - MQTT）

接口及参数

参数字段	字段描述	类型	必须
method	通知内容分类 1. devStatus：设备异常状态通知 2. printRlt：打印结果通知	String	是
devid	机器码	String	是
reqid	请求标识，用于唯一标识当前请求。打印结果回调是使用此参数	String	否
code	通知编码，详细描述参照附录A-3	String	是
message	通知描述	String	否

请求方式： POST

URL地址：三方服务商提供。用户登陆后填写在用户信息-回调地址

Content-Type： application/json

请求示例：

{
  "method": "devStatus",
  "devid": "SW1234567890",
  "reqid": "e970e65af9bd4dfb9400d896607bc812",
  "code": 105,
  "message": "缺纸"
}

返回参数

Content-Type： application/json

参数字段	字段描述	类型
message	ok	String

返回示例：

{
  "message": "OK" --(收到通知请返回"OK")
}

MQTT 回调（订阅方式）

如不便提供公网 HTTP 接口，可选择 MQTT 方式接收同样的回调通知：在开发者中心 - 回调地址中将通知类型设为 2 - MQTT，然后按下表连接平台 MQTT 服务并订阅专属主题即可。推送报文内容与 HTTP 回调完全一致（JSON 结构相同），无需应答。

订阅主题无需自行拼接：在开发者中心 - 回调地址中将通知类型设为 2 - MQTT 并保存，平台即自动生成您的专属回调主题，在「回调地址」处直接查看并复制即可。

连接参数

参数	值	说明
Broker 地址	`mqtt.sw-aiot.com`	平台回调 MQTT 服务器
端口	`1883`	TCP 连接
Username	`saas_reader`	统一用户名，所有开发者相同
Password	`4A80C029D1DBFCB35B017564377ADF45`	统一密码，所有开发者相同

订阅主题（Topic）

/sw-aiot/saas/<ID>/callback

ID 段由平台自动生成（保存 MQTT 回调后，在开发者中心「回调地址」查看完整主题）

说明：每个开发者的主题互不相同，只能收到自己名下设备的通知，请勿将主题透露给第三方。

推送报文

与 HTTP 回调报文一致：

{
  "method": "printRlt",
  "devid": "SW1234567890",
  "reqid": "e970e65af9bd4dfb9400d896607bc812",
  "code": 200,
  "message": "打印成功"
}

method / devid / reqid / code / message 字段含义见上表「接口及参数」；状态码参照下方附录「设备及任务状态码」。

提示：回调接口在线验证工具仅适用于 HTTP 方式；MQTT 方式请用任意 MQTT 客户端（如 mosquitto_sub、MQTTX）连接上表服务并订阅专属主题自测。

设备及任务状态码

设备及接口返回状态码

1. 设备联网状态（查询设备信息时参照）

状态标志	状态描述
`online`	在线
`offline`	离线

2. 设备状态码（推送打印任务、查询设备信息、回调通知时参照）

状态标志	状态描述
0	正常
101	缺纸
102	开盖
103	故障
100	其他错误（查询不到打印机状态，可能通信异常）
109	打印机未接入（针对打印盒子类）
300	固件升级中
301	固件升级中

3. 接口访问返回状态（推送打印任务时参照）

状态标志	状态描述
200	HTTP 访问通过
401	Illegal access (token无效)
500	Operation failed (操作失败)
5000	System exception (系统异常，如提交的JSON格式错误)
5001	The request parameter verification exception (参数校验不通过)
5002	Request parameter parsing exception（请求参数解析异常）
5003	HTTP content type exception (HTTP 内容类型异常)

4. 打印接口调用返回状态（接口访问状态为 200 时，才有内层打印操作的 code）

状态标志	状态描述
0	正常
001	数据保存异常，请检查设备并重推任务
002	设备不存在!（设备不存在，请确认机器码是否正确）
003	当前设备不存在，请确认是否绑定!（设备未绑定，请确认）
011	推送成功，但设备离线，请及时处理（不用重复推）
012	推送成功，请等待，如队列里里已有未打印任务（等待打印，不用重复推）

5. 打印结果状态码（官网平台或回调通知时参照）

状态标志	状态描述
0	打印成功
201	无任务 ID
202	没有内容type
203	无效内容类型type
204	无任务内容
205	无效 MSG，如 MSG 链接解析错误
206	打印内容下载失败
207	打印任务超时
208	打印内容数据格式错误
210	打印内容数据格式错误（兼容旧机型）

打印排版设计

除传统的ESC/POS、TSPL、CPCL指令外，商为云打印设备还支持更智能友好的JSON、XML等格式排版

基于JSON票据排版

票据打印支持以下JSON格式排版属性，支持智能多列(自动换行)、两列左右对齐、局部PNG图片、双排二维码等：

属性	值类型	值说明	说明
type	string	title : 小票标题（居中，字体宽高放大一倍） text : 行字符打印内容 png : png图片base64编码数据或 URL下载链接（建议使用黑白单色图，热敏打印效果最佳） bmp : bitmap图片base64编码数据或 URL下载链接 qrcode : 二维码，支持双排二维码 bc128 : 默认CODE128A bc128a : CODE128A bc128c : CODE128C code39 : CODE39 div_line : 以'-'的行分割线，支持插入居中的文本 div_star : 以'*'的行分割线，支持插入居中的文本 cut : 切刀指令，对应cont全切、半切; plugin / cash : 开钱箱（两种写法等价） feed : 走纸，n 为点数、lines 为行数	string 值为字符串或数组图片最大为60K 最大512个字节 CODE128A支持数字、字母组合； CODE128C纯数字，支持的数字字符数是CODE128A的2倍支持居中插入内容 0：全切 1：半切开钱箱：写入即触发，无需 cont 等参数（对应 ESC/POS 标准开钱箱指令 ESC p 0，引脚 2 脉冲；与 XML 排版 <PLUGIN> 下发的指令一致，需钱箱支持 ESC/POS 引脚 2 接线）
align	string	left : 居左，默认属性 center : 居中 right : 居右	行内容对齐方式
bold	boolean	true : 加粗 false : 不加粗（默认属性）	字体加粗属性；不需要加粗可以不添加
size	string	两个数字组成的字符串，如"11" text / 多列表格 tbody（"AB"：A=横向档位 0-7，B=纵向档位 0-7，实际倍数=档位+1，默认"00"；"11"=放大1倍，"22"=放大2倍）多列表格未写 thead_size 时，表头也使用 size 注意：个别机型 MCU 放大倍数上限为 2 倍，有效取值为 "00"/"01"/"10"/"11"，更大的值会被按 2 倍处理 qrcode（值为"10" - "90"，默认"40"） bc128 （"AB" 即 A对应宽度，B对应高度） A：条码宽度 1-6，默认2 B：代表条码高度，B=0-9，H=（b+1）*3mm，默认2	字体、表格表体、二维码、条码尺寸属性
thead_size	string	可选。格式与表格 size 相同（"AB"，档位 0-7）仅作用于多列表头；省略时表头与表体共用 size	多列表头字号；可与 size 分开设置
line_space	number	表格行间走纸点数 0-255，单位 dot，约 8 点 = 1mm 备注行与商品行之间用 note_space，与下一商品之间才用 line_space	多列表格行距
line_div	number	1：每行前打印 '-' 分割线；0 或不写：不打印对象行可单独覆盖	多列表格行分割线
thead	array/object	key 表头内容 value 列宽占比	多列表头,示例 "thead":{"名称": "50%", "单价": "20%", "数量": "20%", "金额": "10%"} "thead":["50%", "15%", "15%", "20%"],
tbody	array	多列内容数组。每一行可以是：数组：["黄瓜","10斤","","5.00"]，原有写法对象：可在多列下方挂整行备注，并单独指定本行样式 cols：多列内容数组，元素可为字符串/数字，也可为对象 {"t":"内容","size":"11","bold":true,"align":"right","overflow":"clip"} note：整行备注，字符串或字符串数组（每条各占一行） note_size / note_bold / note_align / note_indent / note_space size / bold / underline / strike：本行样式，覆盖表级 line_div：本行是否打分割线，覆盖表级仅写 note 不写 cols 时，只输出一整行（用于分组说明）	备注行紧贴所属商品行；单条 note 转 GBK 后上限约 99 个汉字，更长请拆成数组
col_align	array	可选。每列对齐方式，取 left / center / right 如 ["left","center","right","right"] 未指定的列沿用默认规则：末列右对齐，其余左对齐	多列表格列对齐
overflow	string	wrap：超宽折行，默认 clip：超宽截断 ellipsis：超宽截断并以 .. 结尾	表格列内容超出列宽时的处理；可在表级或单元格级指定
underline strike	boolean/number	underline：true 或 1 细下划线，2 粗下划线，默认关闭 strike：删除线语义，当前机型按下划线呈现可用于 text、表格表级/行级/单元格级、备注行（note_underline / note_strike）表头单独控制用 thead_underline / thead_strike reverse（反白）当前机型不支持，写了会被忽略	字符修饰，常用于退货、作废行
feed	type	走纸元素，用于区块之间留白 n：走纸点行数 1-255，约 8 点 = 1mm（203dpi） lines：走纸行数 1-255 两者都不写按 n=1 处理如 {"type":"feed","n":24}	比打空行更精细的纵向留白
both_sides	array	数组两项：左对齐、右对齐。元素可以是字符串，也可以是对象字符串：["收款金额","258.00"]，整行共用 size / bold 对象：{"t":"￥133.20","size":"11","bold":true}，该侧单独设字号/加粗/下划线如 {"both_sides":["应收", {"t":"￥133.20","size":"11","bold":true}]} 未写的样式继承本行 size / bold	打印内容
hri	number	条码下方字符：0 不显示，1 上方，2 下方（默认），3 上下都显示	bc128 / code39
cont	string/array	text : 字符串，或片段数组（同一行内混排不同字号/加粗）片段元素可为字符串，也可为对象 {"t":"文本","size":"11","bold":true,"underline":1} 片段未写的样式继承本行 size / bold；整行对齐仍由 align 决定如 "cont":[{"t":"合计："},{"t":"￥128.00","size":"11","bold":true}] qrcode 支持数组的cont内容，用于打印双排二维码	打印内容

备注：

png 图片建议为黑白图片，图片宽度像素不超过目标打印宽度最大点数（80mm 对应最大 576 像素，58mm 最大对应 384 像素，110mm 最大对应 832 像素）。
bmp 只支持位深度为 1 的黑白图片。
如图片内容为固定的（如品牌 logo 等），推荐传 URL 链接方式：打印机有类似浏览器的缓存策略，首次打印下载后，如 URL 不变，后续打印直接使用本地缓存图片，省去下载环节。

JSON 票据排版示例

先看完整小票了解全貌，再按需展开专项示例直接复制。

JSON

{
  "print": [
    {"type": "title", "cont": "云味小厨"},
    {"type": "text", "cont": "堂食结账单", "align": "center", "size": "01"},
    {"type": "feed", "n": 8},
    {"type": "text", "cont": "桌号 A12        人数 4"},
    {"type": "text", "cont": "单号 20260920-0087"},
    {"type": "text", "cont": "开单 2026-09-20 12:18    收银 王小明"},
    {"type": "div_line"},
    {
      "size": "00",
      "thead_size": "00",
      "line_space": 12,
      "col_align": ["left", "center", "right", "right"],
      "thead": {"菜品": "42%", "数量": "16%", "单价": "20%", "小计": "22%"},
      "tbody": [
        {"note": "—— 凉菜 ——", "note_align": "center"},
        ["拍黄瓜", 1, "12.00", "12.00"],
        {
          "cols": ["口水鸡", 1, "32.00", "32.00"],
          "note": "备注：少放花椒",
          "note_indent": 2
        },
        {"note": "—— 热菜 ——", "note_align": "center"},
        ["可乐鸡翅", 1, "38.00", "38.00"],
        {
          "cols": ["水煮鱼", 1, "58.00", "58.00"],
          "note": ["备注：微辣、不要香菜", "做法：鱼头单独装盘"],
          "note_indent": 2,
          "note_space": 6
        },
        {
          "cols": [
            {"t": "地三鲜（已退）", "strike": true},
            1,
            "26.00",
            {"t": "-26.00", "strike": true}
          ]
        },
        ["米饭", 4, "2.00", "8.00"]
      ]
    },
    {"type": "div_line"},
    {"both_sides": ["菜品合计", "￥148.00"]},
    {"both_sides": ["会员折扣 9折", "-14.80"]},
    {"type": "feed", "n": 6},
    {"type": "text", "align": "right",
     "cont": [{"t": "应收 "}, {"t": "￥133.20", "size": "11", "bold": true}]},
    {"type": "feed", "n": 6},
    {"both_sides": ["微信支付", "133.20"], "bold": true},
    {"type": "plugin"},
    {"type": "div_line"},
    {"type": "text", "align": "left",
     "cont": [{"t": "本单积分 "}, {"t": "133", "bold": true}, {"t": "  累计 "}, {"t": "3560", "bold": true}]},
    {"type": "feed", "n": 8},
    {"type": "text", "cont": "扫码开发票", "align": "center"},
    {"type": "qrcode", "cont": "https://www.sw-aiot.com/i/20260920-0087", "align": "center", "size": "50"},
    {"type": "bc128", "cont": "202609200087", "align": "center", "size": "12"},
    {"type": "feed", "n": 8},
    {"type": "text", "cont": "谢谢光临 欢迎再次品尝", "align": "center", "bold": true},
    {"type": "div_star", "cont": "本单已结清"},
    {"type": "feed", "lines": 2},
    {"type": "cut", "cont": "1"}
  ]
}

JSON

{
  "print": [
    {"type": "title", "cont": "文本样式"},
    {"type": "text", "cont": "左对齐", "align": "left"},
    {"type": "text", "cont": "居中", "align": "center"},
    {"type": "text", "cont": "右对齐", "align": "right"},
    {"type": "text", "cont": "常规字号 size 00"},
    {"type": "text", "cont": "宽高放大 size 11", "size": "11"},
    {"type": "text", "cont": "加粗 bold", "bold": true},
    {"type": "text", "cont": "细下划线", "underline": 1},
    {"type": "text", "cont": "粗下划线", "underline": 2},
    {"type": "text", "cont": "删除线（当前按下划线呈现）", "strike": true}
  ]
}

JSON

{
  "print": [
    {
      "type": "text",
      "align": "left",
      "cont": [
        {
          "t": "会员："
        },
        {
          "t": "王小明",
          "bold": true
        },
        {
          "t": "  余额 "
        },
        {
          "t": "￥356.80",
          "size": "11"
        }
      ]
    },
    {
      "type": "text",
      "align": "left",
      "cont": [
        {
          "t": "原价 "
        },
        {
          "t": "￥158.00",
          "strike": true
        },
        {
          "t": "  现价 "
        },
        {
          "t": "￥128.00",
          "size": "11",
          "bold": true
        }
      ]
    },
    {
      "type": "text",
      "align": "right",
      "cont": [
        {
          "t": "合计 "
        },
        {
          "t": "￥128.00",
          "size": "11",
          "bold": true
        }
      ]
    }
  ]
}

JSON

{
  "print": [
    {
      "size": "00",
      "thead_size": "11",
      "line_space": 16,
      "line_div": 1,
      "col_align": [
        "left",
        "center",
        "right",
        "right"
      ],
      "thead": {
        "名称": "40%",
        "数量": "20%",
        "单价": "20%",
        "金额": "20%"
      },
      "tbody": [
        [
          "番茄炒蛋",
          2,
          "24.00",
          "48.00"
        ],
        [
          "西红柿炒番茄",
          1,
          "28.00",
          "28.00"
        ],
        [
          "米饭",
          2,
          "2.00",
          "4.00"
        ]
      ]
    }
  ]
}

JSON

{
  "print": [
    {
      "size": "00",
      "col_align": [
        "left",
        "center",
        "right",
        "right"
      ],
      "thead": {
        "商品": "42%",
        "数量": "16%",
        "单价": "20%",
        "小计": "22%"
      },
      "tbody": [
        {
          "note": "—— 热菜 ——",
          "note_align": "center"
        },
        [
          "可乐鸡翅",
          1,
          "38.00",
          "38.00"
        ],
        {
          "cols": [
            "水煮鱼",
            1,
            "58.00",
            "58.00"
          ],
          "note": [
            "备注：微辣、不要香菜",
            "做法：鱼头单独装盘"
          ],
          "note_indent": 2,
          "note_space": 6
        },
        {
          "cols": [
            "拍黄瓜",
            1,
            "12.00",
            "12.00"
          ],
          "strike": true
        }
      ]
    }
  ]
}

JSON

{
  "print": [
    {
      "size": "00",
      "overflow": "wrap",
      "thead": {
        "商品": "50%",
        "数量": "20%",
        "金额": "30%"
      },
      "tbody": [
        [
          "有机黄瓜特级精选装每箱十斤新鲜直供",
          "10",
          "350.00"
        ],
        {
          "cols": [
            {
              "t": "超长名称截断并加省略号",
              "overflow": "ellipsis"
            },
            {
              "t": "2",
              "bold": true,
              "align": "center"
            },
            {
              "t": "36.00",
              "size": "11",
              "bold": true
            }
          ]
        },
        {
          "cols": [
            {
              "t": "已退货商品",
              "strike": true
            },
            "1",
            {
              "t": "-12.00",
              "strike": true,
              "align": "right"
            }
          ]
        }
      ]
    }
  ]
}

JSON

{
  "print": [
    {"both_sides": ["菜品合计", "￥148.00"]},
    {"both_sides": ["会员折扣 9折", "-14.80"]},
    {"both_sides": ["实收金额", "￥133.20"], "size": "11", "bold": true},
    {"both_sides": ["应收", {"t": "￥133.20", "size": "11", "bold": true}]}
  ]
}

JSON

{
  "print": [
    {
      "type": "bc128",
      "cont": "123456789",
      "align": "center",
      "size": "12"
    },
    {
      "type": "code39",
      "cont": "CODE39",
      "align": "center",
      "hri": 2
    },
    {
      "type": "qrcode",
      "cont": "https://www.sw-aiot.com",
      "align": "center",
      "size": "50"
    },
    {
      "type": "qrcode",
      "cont": [
        "https://www.sw-aiot.com",
        "202609200087"
      ],
      "align": "center",
      "size": "04"
    }
  ]
}

JSON

{
  "print": [
    {
      "type": "text",
      "cont": "走纸 24 点（约 3mm）",
      "align": "center"
    },
    {
      "type": "feed",
      "n": 24
    },
    {
      "type": "text",
      "cont": "走纸 2 行",
      "align": "center"
    },
    {
      "type": "feed",
      "lines": 2
    },
    {
      "type": "png",
      "cont": "https://www.sw-aiot.com/images/example_logo.png",
      "align": "center"
    },
    {
      "type": "feed",
      "lines": 2
    },
    {
      "type": "cut",
      "cont": "1"
    }
  ]
}

基于JSON标签排版

本规范定义了一套基于 JSON 格式的标签打印排版语言，通过统一的 JSON 结构描述标签内容与格式，可自动转换为 TSPL或 CPCL打印机指令。支持精确坐标定位、多元素混合排版、批量打印及工业级打印机控制功能。

打开在线打标签

适用范围：支持转换为 TSPL/CPCL 指令的桌面/移动标签打印机，兼容 203/300/600 dpi 分辨率

设计原则：商为标签云打印机统一为TSPL指令，打印云盒可根据实际接的打印机型号选择TSPL或CPCL

全局标签参数

所有参数均为可选，标签内容通过 label 定义：一维数组表示单张标签（元素为打印对象）；二维数组表示一次推送多张不同标签（外层每一项为一张标签的元素列表）。相同内容多份打印请用 COPIES。

属性	类型	取值范围	默认值	说明
SIZE	Array	[宽, 高]	-	标签物理尺寸，单位 mm，例：[76, 130]
DPI	Number	203/300/600	-	打印机分辨率，默认203
DIRECTION	Number	0/1	0	0: 正方向；1: 倒转 180°
DENSITY	Number	1-15	8	打印浓度（1 最浅，15 最深）
SPEED	Number	1-10	5	打印速度（1 最慢，10 最快）
SOUND	Number	0-10	0	打印完成后蜂鸣次数（0 不响）
COPIES	Number	1-999	1	单页打印份数
GAP	Number	0-10	2	标签间隙高度，单位 mm；连续纸模式设为 0
BLACKMARK	Number	0-10	0	黑标高度，单位 mm；与 GAP 二选一，优先 BLACKMARK
OFFSET	Array	[x, y]	[0, 0]	打印原点偏移，单位 mm
CUT	Number	0/1/2	0	0: 不切；1: 全切；2: 半切
PEEL	Number	0/1	0	0: 关闭；1: 开启标签剥离
REWIND	Number	0/1/2	0	0: 关闭；1: 正向回卷；2: 反向回卷
REWIND_OFFSET	Number	0-100	0	反向回卷偏移量，单位 mm；REWIND=2 时必填
FEED	Number	0-100	0	打印完成后额外走纸距离，单位 mm
LANGUAGE	String	TSPL/CPCL	-	强制指定目标打印语言；不填则由转换层自动识别，默认TSPL

公共元素属性

label 数组中每个打印元素均包含以下公共属性，坐标单位为 dot（点），左上角为原点。

属性	类型	取值范围	默认值	说明
type	String	见元素类型	-	打印元素类型，必填
x	Number	≥0	0	元素水平起始坐标，单位 dot
y	Number	≥0	0	元素垂直起始坐标，单位 dot
cont	String	-	-	打印内容，必填（图形元素除外）
r	Number	0/90/180/270	0	元素旋转角度，顺时针旋转

元素类型与专有属性

文本（TEXT）

font 对应 TSPL TEXT x,y,"font",rotation,x-multiplication,y-multiplication,"content" 指令中的字体类型参数。JSON 中必须使用字符串，例如 "font":"1"。字体标识不限于数字，可使用打印机支持的中文字体名称或特殊机型定制字体标识，具体以设备固件及已安装字体库为准。

属性	类型	取值	默认	说明
font	String	打印机支持的字体标识	"0"	TSPL TEXT 字体类型；可为内置字体、中文字体或特殊机型定制字体，实际取值以设备为准
w / h	Number	0-15	0	字体宽/高放大倍数（0=1 倍）；不同机型支持范围可能不同，实际以设备为准
bold	Boolean	true/false	false	是否加粗
underline	Boolean	true/false	false	是否下划线
reverse	Boolean	true/false	false	是否反白显示（黑底白字）
spacing	Number	0-10	0	字符间距，单位 dot

条码

支持类型：BC128、CODE39、EAN13、EAN8、UPC-A、UPC-E、CODE93、ITF、MSI、CODABAR

属性	类型	取值	默认	说明
h	Number	≥0	30	条码高度，单位 dot
show	Number	0/1/2	1	0: 不显示；1: 条码下方；2: 条码上方
narrow	Number	1-6	1	窄条宽度，单位 dot
wide	Number	1-10	2	宽条宽度；CODE128 固定为 1
checksum	Boolean	true/false	true	是否自动计算校验和

二维码

支持类型：QRCODE、PDF417、DATAMATRIX

属性	适用类型	说明
e	QRCODE	容错级别 L/M/Q/H，默认 M
w	QRCODE	模块宽度 1-10 dot，默认 4
version / mask	QRCODE	版本 1-40（0=自动）；掩码 0-7（-1=自动）
w / h	PDF417	模块宽/高 1-10 dot，默认 2
w / e	DATAMATRIX	模块宽度 1-10；纠错级别 0-8，默认 2

图形

支持类型：BAR（直线）、RECT（矩形）、ROUNDRECT（圆角矩形）、CIRCLE（圆形）、ELLIPSE（椭圆）

属性	说明
w	宽度/长度，单位 dot；BAR 为直线长度，CIRCLE 为直径
h	高度/线宽，单位 dot；CIRCLE 无需设置
r	圆角半径，单位 dot（仅 ROUNDRECT）
fill	是否填充图形，默认 false

位图（BITMAP）

属性	说明
cont	Base64 编码的 BMP（位深度为 1）或 PNG 数据，或 HTTP/HTTPS 图片 URL

DPI 自适应转换规则

全局参数中以 mm 为单位的字段（SIZE、GAP、BLACKMARK、OFFSET、FEED、REWIND_OFFSET）会按目标 DPI 自动转换为 dot；元素坐标 x/y 保持 dot 单位不变。

DPI	1mm 约等于 dot 数	说明
203	≈8	行业标准近似值
300	≈12	高精度桌面打印机
600	≈24	工业级高精度打印机

图片按目标 DPI 自动缩放，避免模糊或拉伸
条码/二维码模块宽度自动适配 DPI，保证可扫描性
label 可以是一维数组（单张）或二维数组（一次发送多张不同标签）；相同内容多份请用 COPIES

JSON · 40×30mm · 单张

{
  "SIZE": [40, 30],
  "DIRECTION": 1,
  "DENSITY": 15,
  "label": [
    {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     堂食-2    1/5"},
    {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "芭乐冰沙啵啵         "},
    {"type": "TEXT", "x": 5, "y": 160, "w": 1, "h": 1, "r": 0, "cont": "08-27 10:27　￥19.00"},
    {"type": "TEXT", "x": 5, "y": 190, "w": 1, "h": 1, "r": 0, "cont": "趣围炉烤肉(三元里店)"}
  ]
}

将 label 设为二维数组，外层每个子数组对应一张标签，可在一次任务中打印多张内容不同的标签（如餐饮分杯贴 1/5～5/5）。

JSON · 40×30mm · 5 张不同标签

{
  "SIZE": [40, 30],
  "DIRECTION": 1,
  "DENSITY": 15,
  "label": [
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     堂食-2    1/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "芭乐冰沙啵啵         "},
      {"type": "TEXT", "x": 5, "y": 160, "w": 1, "h": 1, "r": 0, "cont": "08-27 10:27　￥19.00"},
      {"type": "TEXT", "x": 5, "y": 190, "w": 1, "h": 1, "r": 0, "cont": "趣围炉烤肉(三元里店)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     堂食-2    2/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "芭乐冰沙啵啵         "},
      {"type": "TEXT", "x": 5, "y": 160, "w": 1, "h": 1, "r": 0, "cont": "08-27 10:27　￥19.00"},
      {"type": "TEXT", "x": 5, "y": 190, "w": 1, "h": 1, "r": 0, "cont": "趣围炉烤肉(三元里店)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     堂食-2    3/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "芭乐冰沙啵啵         "},
      {"type": "TEXT", "x": 5, "y": 160, "w": 1, "h": 1, "r": 0, "cont": "08-27 10:27　￥19.00"},
      {"type": "TEXT", "x": 5, "y": 190, "w": 1, "h": 1, "r": 0, "cont": "趣围炉烤肉(三元里店)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     堂食-2    4/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "菠萝冰沙-默认        "},
      {"type": "TEXT", "x": 5, "y": 160, "w": 1, "h": 1, "r": 0, "cont": "08-27 10:27　￥19.00"},
      {"type": "TEXT", "x": 5, "y": 190, "w": 1, "h": 1, "r": 0, "cont": "趣围炉烤肉(三元里店)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     堂食-2    5/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "芭乐轻乳茶           "},
      {"type": "TEXT", "x": 5, "y": 160, "w": 1, "h": 1, "r": 0, "cont": "08-27 10:27　￥22.00"},
      {"type": "TEXT", "x": 5, "y": 190, "w": 1, "h": 1, "r": 0, "cont": "趣围炉烤肉(三元里店)"}
    ]
  ]
}

全球语言矢量打印XML排版

本规范基于打印机内置多语言矢量字库，实现智能排版（如画表格）、文字按指定字号矢量放大、多语言混合打印支持（包括维语、蒙语等）、内容基于UTF8编码无需代码页切换。相比传统图形打印，应用开发简单、通信数据量小（文本内容），适合蓝牙、移动网络等高效打印场景。

基于本规范的XML格式排版支持标签、票据两种类型：标签为固定宽、高，每项元素含起始 x、y 坐标；票据为热敏小票流式排版，支持表格多列与自动换行。

规范版本：v1.7（相对 1.6 新增文本删除线 / 下划线 / 反白及内联样式）

编码：UTF-8

接口推送：打印任务 type 设为 4（XML），将排版内容BASE64后填入 message 字段

注：含默认值的属性可省略；坐标单位均为 dot，203 DPI 下 1mm≈8 dot（58mm 小票宽约 384 dot，80mm 约 576 dot）。未写装饰属性时行为与 v1.6 完全兼容。

1、标签排版（根节点 label）

对象	属性	说明
label	width / height	标签宽、高，单位 mm
	dpi	打印分辨率，默认 203
	direction	打印内容方向，0（默认）或 1
	density	浓度 1–15，默认 8
	gap	标签间隙，默认 2mm
	language	指令语言：tspl（默认）、cpcl、ezpl
	copy	打印份数，默认 1

text（标签文本，需 x/y 坐标）

属性	说明
x / y	左上角坐标，单位 dot
font	字号 8–100，数值越大字越大
align	left / center / right
bold	0 不加粗（默认），1 加粗
width	文本限定宽度，超出自动换行，单位 dot
dir	rtl 从右到左，ltr 从左到右
strike	整段删除线：0 无（默认）；1 / true / on 开启
underline	整段下划线：0 无（默认）；1 单下划线；2 双下划线
decoration	CSS 风格组合，如 `line-through underline`（见下文「文本装饰」）
reverse	反白（黑底白字）：0 正常（默认）；1 开启；可与 bold / strike / underline 叠加

barcode / qrcode（标签，需 x/y）

对象	属性	说明
barcode	x, y, height, type（BC128 等）, hrt（0/1 显示字符）	一维条码
qrcode	x, y, size（1–10，默认 2）, ecc（1=L/2=M/3=Q/4=H）	二维码

line / img / 图形（标签）

对象	属性	说明
line	x, y, end_x, end_y, width	直线
img	x, y；内容为 URL 或 Base64	png、bmp 光栅图
rect	x, y, w, h, fill（0/1）, width（线宽）	矩形
roundrect	x, y, w, h, r（圆角）, fill, width	圆角矩形
circle	x, y, r（半径）, fill, width	圆形
ellipse	x, y, w, h, fill	椭圆

2、小票排版（根节点 receipt）

对象	属性	说明
receipt	width	小票宽度 dot；58mm≈384，80mm≈576
	font	全局字号 8–100
	dir	全局强制文字排版方向 rtl / ltr

text（小票文本，自动换行）

属性	说明
align / bold / font / dir	同标签 text，无需 x/y
strike / underline / decoration / reverse	同标签 text；详见下文「文本装饰与内联样式」

table / tr / td（多列表格）

支持：两列左右对齐、多列按占比换行、行内嵌条码/二维码/图片、带边框表格。

对象	属性	说明
table	border	0 无边框；>0 边框线宽 dot
table	div_line	虚线分割线高度（与 border 二选一）
table	font / dir	表格统一字号、方向
tr	—	一行，内嵌 td
td	width	列宽：%30 等百分比，或 dot 绝对宽度（同一 table 只用一种）
td	align / bold / font	单元格可独立设置；可嵌套 barcode、qrcode、img
td	strike / underline / decoration / reverse	文本单元格装饰，语义同 text（见下文）

barcode / qrcode / img / space / line / cut / cash

对象	主要属性	说明
barcode	type, height, readable, align	小票条码；readable：0/1 显示字符
qrcode	align, size（1–10）, ecc（1–4）	小票二维码
img	align, src/内容, width, height	png、jpg、bmp；URL 或 Base64
space	数值	空白行高度 dot，如 <space>20</space>
line	x, end_x, width, dash, font	分割线，标签内可含居中文字
cut	—	<cut></cut> 切刀
cash / plugin	—	开钱箱指令

3、文本装饰与内联样式（v1.7）

适用于矢量 XML 的 <text>（标签 / 小票）与表格文本格 <td>。折行、多语言、RTL 下装饰线跟随字形。未写属性时与 v1.6 行为一致。

整段属性

属性	取值	说明
strike	0 / false / off（默认无）；1 / true / on / single / line-through	整段单删除线，穿过字形中部
underline	0（默认无）；1 / single（单下划线）；2 / double（双下划线）	整段下划线
decoration	空格分隔关键字，如 `line-through underline`	CSS 风格组合：`line-through`/`strike` 开删除线；`underline` 开单下划线；`none` 不开启。推荐整段优先用 strike / underline
reverse	0（默认正常）；1 / true / on / reverse / invert	反白：按文字框铺黑底、文字留白（非整行铺满）；可与 bold、strike、underline、dir="rtl" 叠加。大段反白耗墨较多，建议用于标题或强调行

内联子标签（局部样式）

写在 <text> / <td> 内容内部，仅对包裹的子串生效；不要当作与 text 平级的顶层打印项。文本内容缓冲区上限 1024 字节（含内联 markup）。

标签	说明
<s>…</s>	局部删除线（推荐标准写法）
<del>…</del> / <strike>…</strike>	删除线别名，解析时等同 <s>
<u>…</u>	局部下划线
<b>…</b> / <i>…</i>	局部加粗 / 斜体
<span>、<tt>、<big>、<small>、<sub>、<sup>	Pango markup 子集（高级，慎用）

适用范围

通路	是否支持
矢量 XML：<receipt> / <label> / 表格文本 <td>	✅ 支持 strike、underline、decoration、reverse 及内联标签
简易 XML（<B>/<C>/<BOLD>/<BR> 等 ESC 通路）	❌ 不支持
JSON 标签 / JSON 票据排版	❌ 本次矢量 XML 能力不适用于 JSON 通路

附录：条码类型与图片写法

序号	类型	别名	说明
1	CODE128	BC128	默认一维码
2	CODE39	BC39	Code 39
3–9	CODE93, EAN13, EAN8, UPCA, UPCE, ITF, CODABAR	I25 等	常见商品/物流条码
10–16	QRCODE, PDF417, DATAMATRIX, AZTEC, MAXICODE, MICROQR, HANXIN	—	二维码（type 名称大写）

图片写法

img 元素支持以下三种写法；小票排版可用 align 控制对齐，标签排版需配合 x、y 坐标。

方式一 URL 作为标签内容

<img align="center">http://example.com/logo.png</img>

方式二 src 属性指定 URL

<img src="http://example.com/logo.png" align="center"></img>

方式三 Base64 内嵌，可指定 width / height

<img src="data:image/png;base64,iVBORw0KGgo..." width="200" height="150"/>

使用说明

标签排版使用 <label> 根节点；小票排版使用 <receipt>
与简易 XML 排版（<BR>、<CB> 等）为两套语法，请勿混用；删除线 / 下划线 / 反白仅矢量 <receipt>/<label> 通路有效
同一 table 内列宽须统一用百分比或统一用 dot
整段装饰用 strike / underline / reverse；局部改价、划删用内容内 <s>（或 <del>）

XML

<label width="50mm" height="40mm" copy="1" dpi="203">
    <text x="10" y="20" font="24" bold="0" dir="rtl">拉面 ەنمەگە</text>
    <text x="10" y="60" font="16" bold="0" dir="rtl">蔬菜 菜</text>
    <barcode x="10" y="160" hrt="1" height="30" type="BC128">1234567890</barcode>
    <qrcode x="240" y="160" size="2">123456789</qrcode>
    <rect x="10" y="50" w="200" h="80" fill="0" width="2"/>
    <circle x="250" y="100" r="40" fill="0" width="3"/>
    <roundrect x="10" y="320" w="200" h="70" r="12" fill="0" width="2"/>
    <line x="10" y="300" width="3" end_x="200" end_y="300"></line>
    <img x="10" y="200">http://example.com/test.png</img>
</label>

XML

<receipt width="576" font="18">
    <text font="8" align="center" bold="1">文本行8号</text>
    <text font="48" align="center" bold="1">标题行48号</text>
    <text font="72" align="center" bold="1">标题行72号</text>
    <line dash="8" width="3" font="18">分割线</line>
    <table>
        <tr>
            <td align="left">第一列</td>
            <td align="right" font="36" bold="1">第二列</td>
        </tr>
    </table>
    <table border="1">
        <tr>
            <td width="%30">标题列 1</td>
            <td width="%40">标题列 2</td>
            <td width="%30">标题列 3</td>
        </tr>
        <tr><td>内容 1-1</td><td>内容 1-2</td><td>内容 1-3</td></tr>
        <tr><td>内容 2-1</td><td>内容 2-2</td><td>内容 2-3</td></tr>
    </table>
    <space>30</space>
    <table>
        <tr>
            <td width="%50">文本与二维码并列</td>
            <td width="%50"><qrcode size="3">123456789</qrcode></td>
        </tr>
    </table>
    <table>
        <tr>
            <td><barcode type="BC128" height="30" readable="1">1234567888</barcode></td>
            <td><qrcode align="left">11222222222222</qrcode></td>
        </tr>
    </table>
    <img align="center">http://example.com/test.png</img>
    <cut></cut>
</receipt>

XML

<receipt width="576" font="18">
    <text font="36" align="center">多语言矢量打印</text>
    <text font="8" align="center">8号字体打印</text>
    <text font="64" align="center">64号字体打印</text>
    <table>
        <tr><td width="%30">英语</td><td width="%70">Multilingual tests for thermal printers</td></tr>
        <tr><td>中文简体</td><td>热敏打印机多语言测试</td></tr>
        <tr><td>中文繁体</td><td>熱敏打印機多語言測試</td></tr>
        <tr><td>日语</td><td>サーマルプリンタの多言語テスト</td></tr>
        <tr><td>韩语</td><td>열감 프린터 다국어 테스트</td></tr>
        <tr><td>阿拉伯语</td><td>قاراپايدار چاپقۇچى</td></tr>
        <tr><td>蒙古语</td><td>Өгтгөлтөрөгч олон хэл тест</td></tr>
        <tr><td>德语</td><td>Mehrsprachige Tests für Thermoprintern</td></tr>
        <tr><td>泰语</td><td>ทดสอบภาษามายากสำหรับเครื่องพิมพ์ความร้อน</td></tr>
        <tr><td>越南语</td><td>Kiểm tra đa ngôn ngữ cho máy in nhiệt</td></tr>
    </table>
    <table>
        <tr>
            <td width="%50">文本与图形或条码并列</td>
            <td width="%50"><qrcode size="3">123456789</qrcode></td>
        </tr>
    </table>
    <barcode type="BC128" height="30" readable="1">1234567888</barcode>
    <space>20</space>
    <qrcode align="left">11222222222222</qrcode>
    <cut></cut>
</receipt>

XML · v1.7 文本装饰

<receipt width="576">
    <text align="left" strike="1">整行删除线：本行作废 ABC 123</text>
    <text align="left" underline="1">整行下划线：合计金额</text>
    <text align="left" decoration="line-through underline">删除线+下划线</text>
    <text align="left" underline="2">双下划线：应收合计</text>
    <text align="center" font="28" bold="1" reverse="1">退 货 单</text>
    <text align="left" reverse="1" underline="1">反白 + 下划线</text>
    <text align="left">原价 <s>¥100.00</s> 现价 ¥80.00</text>
    <text align="left">已取消：<del>美式咖啡 ×1</del></text>
    <table>
        <tr>
            <td width="%50" strike="1">已退货商品</td>
            <td width="%50" align="right" strike="1">¥12.00</td>
        </tr>
        <tr>
            <td width="%50" reverse="1">反白单元格</td>
            <td width="%50" align="right">¥8.00</td>
        </tr>
    </table>
    <cut></cut>
</receipt>

<!-- 标签模式同样支持 -->
<label width="50" height="30" dpi="203">
    <text x="10" y="20" font="24" strike="1">作废品</text>
    <text x="10" y="50" font="18">SKU <s>A-1001</s> → A-1002</text>
</label>

XML · CODE39 / CODE128 / UPCA / PDF417 / HANXIN / QR

<receipt width="576" font="18">
    <text font="8" align="center" bold="1">文本行8号</text>
    <text font="48" align="center" bold="1">标题行48号</text>
    <text font="72" align="center" bold="1">标题行72号</text>
    <line dash="8" width="3" font="18">分割线</line>
    <table>
        <tr>
            <td align="left">第一列</td>
            <td align="right" font="36" bold="1">第二列</td>
        </tr>
    </table>
    <table border="1">
        <tr>
            <td width="%30">标题列 1</td>
            <td width="%40">标题列 2</td>
            <td width="%30">标题列 3</td>
        </tr>
        <tr><td>内容 1-1</td><td>内容 1-2</td><td>内容 1-3</td></tr>
        <tr><td>内容 2-1</td><td>内容 2-2</td><td>内容 2-3</td></tr>
        <tr>
            <td>内容 3-1</td>
            <td>内容 3-2, 列内容自动换行</td>
            <td>内容 3-3, 列内容自动换行</td>
        </tr>
    </table>
    <space>30</space>
    <line dash="8" width="3" font="18">分割线</line>
    <table space="10">
        <tr>
            <td width="%50">文本与图形或条码并列文本内容自动换行</td>
            <td width="%50"><qrcode size="3">123456789</qrcode></td>
        </tr>
        <space>50</space>
        <tr>
            <td width="%30">PDF417</td>
            <td width="%70"><barcode type="PDF417" height="50">1234567888</barcode></td>
        </tr>
        <tr>
            <td width="%30">UPCA</td>
            <td width="%70"><barcode type="UPCA" height="30" readable="1">1234567888</barcode></td>
        </tr>
        <tr>
            <td width="%30">HANXIN</td>
            <td width="%70"><barcode type="HANXIN" height="50" size="3">1234567888</barcode></td>
        </tr>
    </table>
    <space>30</space>
    <table>
        <tr>
            <td width="%60"><barcode type="CODE39" height="30" readable="1">1234567888</barcode></td>
            <td width="%40"><barcode type="CODE128" height="30" readable="1">1234567888</barcode></td>
        </tr>
    </table>
    <img align="center">https://www.sw-aiot.com/images/example_logo.png</img>
    <cut></cut>
</receipt>

简易XML排版

兼容市面其他厂商常用的简易XML排版：

标签对象	说明	备注
<BR>	换行符	每一行结尾均需包含换行符
<CUT>	切刀指令	带切刀机型有效
<IMG></IMG>	Bitmap图片的base64编码	仅支持8位灰度位图，Base64编码后不超过6KB
<PLUGIN>	开钱箱指令	支持钱箱接口机型有效
<CB></CB>	放大1倍并居中	字符有效
<B></B>	放大一倍	字符有效
<L></L>	字体变高一倍	字符有效
<W></W>	字体变宽一倍	字符有效
<QR></QR>	二维码	单个小票仅支持一个二维码二维码最多支持256个字符支持<QR:n></QR>方式设置二维码大小，n为数字，默认5，范围1-15
<C></C>	行内容居中	排版默认居左，即不包含<C>及<RIGHT>标签时居左
<RIGHT></RIGHT>	行内容居右
<BOLD></BOLD>	字体加粗
<BC128></BC128>	CODE128码	最多支持14个数字及大写字母组合
<BC128_A></BC128_A>	CODE128码	最多支持14个数字及大写字母组合
<BC128_C></BC128_C>	CODE128码	最多支持22个纯数字

排版格式选择建议

JSON格式：结构化数据，复杂排版，适合需要程序动态生成的场景，支持票据和标签两种打印模式，所有云打印设备都支持
矢量XML格式：基于云打印机内置矢量字库，根节点 <label>（标签坐标排版）或 <receipt>（小票流式排版），支持万国语言、任意字号与图形元素，适合 M 系列多语言机型
简易XML格式：兼容其他厂商的 <BR>、<CB> 等标签，简洁易读，适合简单小票排版，所有票据打印机都支持

商为云打印 API 开发文档

快速开始

5分钟完成首次打印

快速接入

在线调试

选择鉴权方式（请先二选一）

标签排版与可视化编辑

协议定义

支持的打印机类型

协议规范

打印内容排版

设备本地配网协议（蓝牙 BLE）

操作流程

API接口

固定验签的接口

通用规则：

设备绑定 接口调试

设备解绑 接口调试

文本打印任务推送 接口调试

文件打印任务推送 接口调试

语音播报消息推送 接口调试

设备信息查询

待打印任务队列清空 接口调试

定期刷新token的接口

登录授权，获取token 接口调试

password参数生成说明

1.参数排序及拼接

password生成参数（参数均不可为空）

2. MD5生成password

password生成示例

设备绑定 接口调试

设备解绑 接口调试

文本打印任务推送 接口调试

文件打印任务推送

语音播报消息推送

设备信息查询

待打印任务队列清空 接口调试

设备状态及打印结果回调

设备状态/任务结果回调

接口及参数

返回参数

MQTT 回调（订阅方式）

连接参数

订阅主题（Topic）

推送报文

设备及任务状态码

设备及接口返回状态码

1. 设备联网状态（查询设备信息时参照）

2. 设备状态码（推送打印任务、查询设备信息、回调通知时参照）

3. 接口访问返回状态（推送打印任务时参照）

4. 打印接口调用返回状态（接口访问状态为 200 时，才有内层打印操作的 code）

5. 打印结果状态码（官网平台或回调通知时参照）

打印排版设计

基于JSON票据排版

JSON 票据排版示例

基于JSON标签排版

全局标签参数

公共元素属性

元素类型与专有属性

文本（TEXT）

条码

二维码

图形

位图（BITMAP）

DPI 自适应转换规则

全球语言矢量打印XML排版

1、标签排版（根节点 label）

text（标签文本，需 x/y 坐标）

barcode / qrcode（标签，需 x/y）

line / img / 图形（标签）

2、小票排版（根节点 receipt）

text（小票文本，自动换行）

table / tr / td（多列表格）

barcode / qrcode / img / space / line / cut / cash

3、文本装饰与内联样式（v1.7）

整段属性

内联子标签（局部样式）

适用范围

附录：条码类型与图片写法

图片写法

设备绑定接口调试

设备解绑接口调试

文本打印任务推送接口调试

文件打印任务推送接口调试

语音播报消息推送接口调试

待打印任务队列清空接口调试

设备绑定接口调试

设备解绑接口调试

文本打印任务推送接口调试

待打印任务队列清空接口调试