设备作为 MQTT Client 直连您自建或第三方 Broker，跳过商为云。打印内容、订单与金额全程留在您自己的服务器上，适用于金融 / 医疗 / 政务等对数据自主有硬要求的场景。
打印任务由您的服务器直接下发到设备，订单、金额、收件人信息不经过商为云，满足数据本地化与等保合规要求。
每台设备以自身 SN 作为 ClientID 与鉴权身份，配合 Broker ACL 限定可读写的主题，单台凭证泄露不波及整批设备。
已在使用阿里云 IoT 或腾讯云 IoT Hub 的团队，按三元组接入即可，无需新建一套消息通道，设备直接并入既有设备管理体系。
阿里云、腾讯云按厂商标准协议接入，端口、TLS 与签名算法沿用厂商规定，无需单独配置传输层参数；TLS 开关与 CA 配置仅适用于自建 / 第三方 MQTT。
| 服务器类型 | 明文端口 | TLS 端口 | 连接参数来源 |
|---|---|---|---|
| 自建 / 第三方 MQTT | 1883 | 8883 | Username / Password / ClientID 均由客户自行设定（仅此类需单独配置 TLS） |
| 阿里云 IoT | 厂商默认 | 厂商 TLS 端口 | ProductKey + DeviceName + DeviceSecret（三元组） |
| 腾讯云 IoT Hub | 厂商默认 | 厂商 TLS 端口 | ProductId + DeviceName + DeviceSecret（三元组） |
| 电信云及其他 | 按服务商规范 | 请联系商务确认 | |
以下为协议层的固定约定，不建议在对接时自行调整；标注「配置写入」的参数由 PC 端配置工具经 USB 写入设备，无需设备联网。
设备只做出站连接，不开放任何入站端口，因此无需公网 IP、无需在防火墙上做端口映射。请在设备的出口策略上按实际使用的功能放行以下目标。
| 协议 / 端口 | 用途 | 说明 |
|---|---|---|
| TCP 1883 / 8883 | MQTT / MQTTS 长连接 | 到 Broker 的连接，按实际配置端口放行（启用 TLS 时为 8883）。是全程持续占用的长连接。 |
| TCP 80 / 443 | 内容下载 / 在线更新 | 使用 URL 方式下发打印内容，或固件与语音包在线更新时才需要。URL 必须使用 https。 |
明文模式下账号密码与打印内容均以明文过网，不满足多数客户的合规要求。对外部署建议默认使用 MQTTS 8883 交付。
| TLS 版本 | ≥ TLS 1.2，不支持 SSL 3.0 / TLS 1.0 / 1.1 |
|---|---|
| 公钥算法 | RSA ≤ 2048 位，或 ECDSA P-256 |
| 签名算法 | SHA-256 及以上 |
| 主机名校验 | 证书 CN 或 SAN 必须匹配设备填写的地址（用于 SNI 与主机名校验） |
| IP 直连 | 地址填 IP 时，证书必须带 SAN:IP，仅有 CN 会校验失败 |
| 有效期 | 建议 ≤ 2 年，建议到期前 30 天启动轮换 |
| 吊销检查 | 不支持 CRL / OCSP，风险通过更换 CA + 重新写号处理 |
以下能力当前版本不支持，或仅在部分机型上支持。请在方案设计与选型阶段据此评估，避免把不支持的能力写进技术方案。
| 能力 | 支持 | 说明 |
|---|---|---|
| MQTT over WebSocket | ✘ | 仅支持 TCP 之上的 MQTT / MQTTS |
| QoS 2 | ✘ | 最高 QoS 1 |
| Retain 消息 | ✘ | 协议不使用 Retain，打印任务禁止使用 |
| 通配符订阅 | ✘ | 单条精确主题，不支持 + / # |
| 共享订阅 / 桥接 | ✘ | 设备是其下行主题的单一订阅者 |
| 分段下载 / 断点续传 | ✘ | 打印内容一次下发完整 |
| 双向 TLS（mTLS） | ✘ | 当前不提供设备证书写入通道，如需请走定制 |
| PSK / TLS-SRP | ✘ | — |
| DER / PFX 证书 | ✘ | 仅接受 PEM |
| CRL / OCSP 吊销检查 | ✘ | 依赖更换 CA |
| MQTT 5.0 | 部分 | 3.1.1 为全机型基线；5.0 仅部分机型支持，需以机型规格书为准 |
| 写入自定义 CA | 部分 | 仅部分机型支持，需以机型规格书为准 |
下行报文为 UTF-8 JSON，QoS 1，Retain 0。通过 type 指定排版方式，通过 contents 承载内容。
| type | 含义 | contents 形态 |
|---|---|---|
| 1 | ESC/POS 指令 | string（Base64 编码的 ESC 指令） |
| 2 | CPCL | string |
| 3 | TSPL | string |
| 4 | XML 排版 | string。基础 XML 兼容主流云打印平台；矢量多语言 XML 限 M 后缀机型，支持多语种与 RTL 排版 |
| 5 | JSON 排版 | Array（票据）/ Object（标签） |
| 6 | PNG 图片 | string：图片 URL 或 Base64 内容 |
| 99 | 设备配置管理 | Object（音量、重启、默认打印语言等） |
| 100 | 支付结果通知 | 用于驱动支付到账播报，具体实现请联系商务确认 |
| id | 必填。任务 ID，0–4294967295，服务端需确保不重复，设备上报结果时原样回带 |
|---|---|
| type | 必填。排版类型，取值见上表 |
| contents | 必填。打印内容，结构随 type 变化 |
| pWidth | 纸宽 mm：58（默认）/ 80 / 110 |
| pCopy | 打印份数，默认 1 |
| pType | 纸类型：1 连续纸 / 2 标签纸 / 3 黑标纸 / 4 穿孔纸 / 8 连续纸（标签指令打小票）。标签打印必传 |
| vType / vMessage | 语音播报类型与文本，用于订单到账播报 |
| gateway | 仅 WiFi + 网口版打印云盒：转发到本机 USB 打印机或指定局域网网络打印机 |
| expire / force | 任务有效期与强制补打开关 规划中 |
| devicename | 必填。设备 SN，与 ClientID 一致 |
|---|---|
| id | 打印结果上报时必填；纯状态上报不带此字段 |
| code | 状态码，见下方「任务结果与状态码」。状态类与结果类上报必带，扫码 / 按键事件不带 |
| imei / iccid | 仅 4G 机型，随上线报文上报一次 |
| scan_content | 扫码机型上传的条码 / 二维码内容 |
| keyevent | 按键事件，仅带按键机型上报 规划中 |
2xx · 任务结果
上报必带 id，表示某一笔任务的最终结果或执行状态，走任务状态机。
1xx · 打印机状态
上报不带 id，只说明这台打印机当前的硬件状态，不改变任何任务状态。
0 · 成功
跨两类的特殊码：带 id 时为「该任务打印成功」，不带 id 时为「打印机从异常恢复」。
| 0 | 成功：带 id 为任务打印完成；不带 id 为打印机恢复正常 |
|---|---|
| 100 | 未知错误 / 通信异常，需现场排查网络 |
| 101 | 缺纸：通知商户装纸，恢复后上报 0 |
| 102 | 开盖：同上 |
| 103 | 打印机过热：等待降温，勿连续重发 |
| 107 | 设备离线：仅由 Broker 代发的遗嘱消息产生，设备不会主动上报 |
| 109 | 打印机未连接 / 连接失败：云盒未检测到打印机，不代表云盒离线 |
| 201–208 | 参数与内容类错误：缺字段、type 无效、下载错误、内容超缓冲区、格式错误等 |
| 209 | 重复任务：同一 id 已打印过，属正常防重，服务端据此确认幂等 |
| 210 | 受阻，已排队等待（非终态、不代表异常）。任务已受理但暂时无法出票，等待设备恢复后自动补打并上报终态 |
|---|---|
| 211 | 设备忙，队列已满（非终态）。任务未被接收，退避后重发 |
| 212 | 任务过期被丢弃（终态）。自受理起超过 expire 秒仍未执行 |
| 213 | 硬件故障，打印放弃（终态）。缺纸 / 开盖等待超时，或出现不可恢复故障 |
自建或选择阿里云 / 腾讯云 IoT，创建对应设备并取得连接参数与三元组。
用 PC 端配置工具经 USB 写入服务器地址、端口、鉴权信息与主题。
按协议实现任务下发与状态上报，订阅与发布主题 QoS 均为 1。
确认首次出票、结果回执与缺纸 / 开盖等状态上报，完成验收。