Developer Docs - SW-AIOT

Fixed-signature APIs

Each request computes a static signature. Paths are identical to China (/api/printer/*); only the host is https://api.sw-aiot.com.

Common rules:

API base URL:https://api.sw-aiot.com/api/printer/
Method:POST
Content-Type:application/json
Headers:
token: md5(secret=xxx&times=xxxx&username=xxxx)
Note: the result is a 32-character hex value (case-insensitive).

Required request parameters (must match username and times used in the header token):

Parameter	Description	Type	Required	Notes
username	Username	String	Yes	Developer account username
times	Timestamp	Long	Yes	13-digit millisecond timestamp; must match times used in the request-header token

Bind printer API debug

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

Method:POST

Content-Type:application/json

Headers:token = md5(secret=xxx&times=xxxx&username=xxxx)

Request parameters:

Parameter	Description	Type	Required	Notes
username	Username	String	Yes	Developer account username
times	Timestamp	Long	Yes	13-digit millisecond timestamp
devid	Device ID	String	Yes	Device machine code
key	Device PIN	String	Yes	4-digit Device PIN on the label (API field name: key)
nickname	Device name	String	No	Device nickname
timeout	Timeout	Integer	No	Message TTL in seconds; recommended 1800

Request example:

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "key": "4463",
    "nickname": "Test device",
    "timeout": 1800
}

Unbind printer API debug

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

Method:POST

Content-Type:application/json

Headers:token = md5(secret=xxx&times=xxxx&username=xxxx)

Request parameters:

Parameter	Description	Type	Required	Notes
username	Username	String	Yes	Developer account username
times	Timestamp	Long	Yes	13-digit millisecond timestamp
devid	Device ID	String	Yes	Device machine code
key	Device PIN	String	Yes	4-digit Device PIN on the label (API field name: key)

Request example:

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

Text print push API debug

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

Method:POST

Content-Type:application/json

Headers:token = md5(secret=xxx&times=xxxx&username=xxxx)

Request parameters:

Parameter	Description	Type	Required	Notes
username	Username	String	Yes	Developer account username
times	Timestamp	Long	Yes	13-digit millisecond timestamp
devid	Device ID	String	Yes	Device machine code
reqid	Request ID	String	Yes	Unique request ID for job tracking
message	Print content	String	Yes	Print text payload
type	Job type	Integer	Yes	1:ESC 2:CPCL 3:TSPL 4:XML 5:JSON 6:IMG 7:PDF
pcopy	Print copies	Integer	No	Number of copies. Default: 1
vtype	Audio type	Integer	No	-1: no voice; 0: custom TTS; >=1: play voice by ID*
vmessage	TTS voice content	String	No	Max 60 characters

Request example:

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "reqid": "e970e65af9bd4dfb9400d896607bc812",
    "message": "Print text content...",
    "type": 5,
    "pcopy": 1,
    "vtype": -1
}

Voice broadcast push API debug

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

Method:POST

Content-Type:application/json

Headers:token = md5(secret=xxx&times=xxxx&username=xxxx)

Request parameters:

Parameter	Description	Type	Required	Notes
username	Username	String	Yes	Developer account username
times	Timestamp	Long	Yes	13-digit millisecond timestamp
devid	Device ID	String	Yes	Device machine code
reqid	Request ID	String	Yes	Unique request ID for job tracking
vmessage	Voice content	String	Yes	Voice broadcast text
vtype	Audio type	Integer	Yes	Voice broadcast type

Request example:

{
    "username": "your_username",
    "times": 1683916200000,
    "devid": "SW1234567890",
    "reqid": "e970e65af9bd4dfb9400d896607bc812",
    "vmessage": "You have a new order",
    "vtype": 0
}

Get device info API debug

API description:

This API returns device information.

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

Method:GET

Content-Type:application/json

Headers:token = md5(secret=xxx&times=xxxx&username=xxxx)

Request parameters:

Note: devid is a URL path parameter; username and times are URL query parameters and are used in the header token.

Parameter	Description	Type	Required	Notes
devid	Machine code	String	Yes	Device ID (URL path parameter)
username	Username	String	Yes	Developer account username (URL query parameter)
times	Timestamp	Long	Yes	13-digit millisecond timestamp (URL query parameter)

Request example:

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

Response parameters:

Response field	Description	Type
code	Response code: 200 success; non-200 failure	int
message	Response message for the code	String
success	Success flag	Boolean
data	Device info	Json

Response example:

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

Clear print queue API debug

API description:

This API clears pending jobs in the print queue by machine code.

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

Method:POST

Content-Type:application/json

Headers:token = md5(secret=xxx&times=xxxx&username=xxxx)

Request parameters:

Parameter	Description	Type	Required	Notes
username	Username	String	Yes	Developer account username
times	Timestamp	Long	Yes	13-digit millisecond timestamp
devid	Machine code	String	Yes	Device machine code

Request example:

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

Response notes:

On success, returns true

Device status & print result callback

This section describes data callbacks: print result, device online/offline changes, and device fault status.

The callback URL is provided by your application. Our servers POST notifications with fixed parameters.

Device status / job result callback

Notify method: HTTP

Endpoint & parameters

Parameter	Description	Type	Required
method	Notification category 1. devStatus: device abnormal status 2. printRlt: print result	String	Yes
devid	Machine code	String	Yes
reqid	Request ID uniquely identifying the request. Used for print-result callbacks	String	No
code	Notification code; see appendix A-3 for details	String	Yes
message	Notification message	String	No

Request method: POST

URL: Provided by your service. After sign-in, set it under user info → callback URL

Content-Type: application/json

Request example:

{
  "method": "devStatus",
  "devid": "SW1234567890",
  "reqid": "e970e65af9bd4dfb9400d896607bc812",
  "code": 104,
  "message": "Paper low"
}

Response parameters

Content-Type: application/json

Parameter	Description	Type
message	ok	String

Response example:

{
  "message": "OK" -- (return "OK" when you receive the notification)
}

Device & job status codes

Device & API status codes

1. Device network status (when querying device info)

Code	Description
`online`	Online
`offline`	Offline

2. Device status codes (print push, device info query, callbacks)

Code	Description
0	Normal
101	Out of paper
102	Cover open
103	Fault
100	Other error (printer status unavailable; possible communication issue)
109	Printer not connected (cloud-box devices)
300	Firmware upgrading
301	Firmware upgrading

3. API access status (when pushing print jobs)

Code	Description
200	HTTP access OK
401	Illegal access (invalid token)
500	Operation failed
5000	System exception (e.g. invalid submitted JSON)
5001	The request parameter verification exception
5002	Request parameter parsing exception
5003	HTTP content type exception

4. Print API operation status (inner code only when HTTP access status is 200)

Code	Description
0	Normal
001	Data save error; check the device and re-push the job
002	Device does not exist (verify machine code)
003	Device not found / not bound (verify binding)
011	Push succeeded but device is offline (do not re-push)
012	Push succeeded; jobs already queued (wait to print; do not re-push)

5. Print result status codes (portal or callbacks)

Code	Description
0	Print succeeded
201	Missing job ID
202	Missing content type
203	Invalid content type
204	Missing job content
205	Invalid MSG (e.g. link parse error)
206	Print content download failed
207	Print job timed out
210	Print content format error

Besides ESC/POS, TSPL, and CPCL, SW-AIOT cloud printers also support smarter JSON and XML layouts

JSON ticket layout

Ticket printing supports the following JSON layout attributes: smart multi-column (auto wrap), two-column left/right align, partial PNG images, dual QR codes, and more:

Attribute	Value type	Value notes	Notes
type	string	title: receipt title (centered; width/height ×2) text: line text content png: PNG image as base64 or download URL bmp: bitmap image as base64 or download URL qrcode: QR code; supports dual QR bc128: default CODE128A bc128a : CODE128A bc128c : CODE128C code39 : CODE39 div_line: '-' divider line; supports centered inset text div_star: '*' divider line; supports centered inset text cut: cutter command; cont = full/half cut plugin: open cash drawer	string String or array Image max 6KB Max 512 bytes CODE128A supports digits and letters; CODE128C digits only; digit capacity is 2× CODE128A Supports centered inset text 0: full cut 1: half cut
align	string	left: left align (default) center: center right: right	Line content alignment/td>
bold	boolean	true: bold false: not bold (default)	Bold flag; omit if not needed
size	string	Two-digit string such as "11"; meaning depends on type. For text ("AB"): width×(A+1), height×(B+1) — e.g. "AB" means ×4 / ×3 A = width multiplier 0–7, default 0 B = height multiplier 0–7, default 0 qrcode: "10"–"90", default "40" bc128: "AB" where A=width, B=height A: barcode width 1–6, default 2 B: barcode height 0–9; H=(b+1)*3mm, default 2	Font / QR / barcode size
thead	array/object	key: header text value: column width ratio	Multi-column headers, e.g. "thead":{"Name": "50%", "Price": "20%", "Qty": "20%", "Amount": "10%"} "thead":["50%", "15%", "15%", "20%"],
tbody	array	Multi-column Content is an array
both_sides	array	Array of two strings (first left-aligned, second right-aligned), e.g. ["Amount","258.00"]	Print content
cont	string/array	text: string or array of two strings qrcode: cont may be an array for dual QR codes	Print content

JSON

{"print":[
    {"cont":"Title","type":"title"},
    {"cont":"Text line","type":"text"},
    {"cont":"Bold text line","type":"text","bold":true},
    {"cont":"Font scale ×1","type":"text","size":"11"},
    {"cont":"Font scale ×2","type":"text","size":"22"},
    {"cont":"","type":"text"},
    {"type":"div_line","cont":"Multi-column with headers"},
    {
        "thead":{"Name": "50%", "Price": "20%", "Qty": "20%", "Amount": "10%"},
        "tbody": [
            ["Tomato eggs", 24, 2, 48],
            ["Tomato stir-fry", 24, 7, 168],
            ["Egg mix", 24, 1, 24],
            ["Spicy potato stir-fry", 24, 3, 72]
        ]
    },
    {"cont":"","type":"text"},
    {"type":"div_line", "cont":"Multi-column without headers"},
    {
        "line_space":5,
        "thead":["50%", "15%", "15%", "20%"],
        "tbody": [
            ["Tomato eggs", 24, 2, 48],
            ["Tomato stir-fry", 24, 7, 168],
            ["Egg mix", 24, 1, 24],
            ["Spicy potato stir-fry", 24, 3, 72]
        ]
    },
    {"cont":"","type":"text"},
    {"type":"div_star","cont":"Multi-column scale & divider"},
    {
        "size":"11",
        "line_div":1,
        "thead":{"No.": "20%", "Name": "80%"}, 
        "tbody":[
            [1, "Tomato eggs + beef stew + stir-fried pork + soup"], 
            [2, "123456788888"], 
            [3, "Egg mix"]
        ]
    },
    {"cont":"","type":"text"},
    {"type":"div_star","cont":"CODE128 barcode example"},
    {"cont":"123456789","type":"bc128","align":"left","size":"11"},
    {"cont":"123456789","type":"bc128","align":"left","size":"22"},
    {"cont":"123456789","type":"bc128","align":"left","size":"33"},
    {"type":"div_star","cont":"CODE39 barcode example"},
    {"cont":"123456789","type":"code39","align":"left","hri":2},
    {"cont":"","type":"text"},
    {"type":"div_star","cont":"Two-column L/R align example"},
    {"both_sides":["Amount","258.00"]},
    {"both_sides":["Amount","258.00"], "size":"11"}, 
    {"cont":"","type":"text"},
    {"type":"div_star","cont":"QR code example"},
    {"cont":"http://cloud.sw-aiot.com","type":"qrcode","align":"center"},
    {"cont":"http://cloud.sw-aiot.com","type":"qrcode","align":"center","size":"60"},
    {"type":"div_star","cont":"Dual QR code example"},
    {"cont":["http://cloud.sw-aiot.com","1234567890123bb44"],"type":"qrcode","align":"right","size":"06"},
    {"cont":"","type":"text"},
    {"type":"div_star","cont":"PNG image print example"},
    {"type":"png","cont":"http://linxiaoge.oss-cn-shanghai.aliyuncs.com/ic/add/test.png","align":"center"},
    {"cont":"1","type":"cut"}
]
}

JSON label layout

This spec defines a JSON label layout language. A unified JSON structure describes label content and format and converts to TSPL or CPCL. It supports precise coordinates, mixed elements, batch print, and industrial printer controls.

Scope: Desktop/mobile label printers convertible to TSPL/CPCL; 203/300/600 dpi

Design: SW-AIOT label cloud printers use TSPL; cloud boxes may use TSPL or CPCL based on the attached printer

Global label parameters

All parameters are optional. Label content is defined by label: a 1D array means a single label (elements are print objects); a 2D array means multiple different labels in one push (each outer item is one label’s element list). For identical content printed multiple times, use COPIES.

Attribute	Type	Range	Default	Notes
SIZE	Array	[width, height]	-	Physical label size in mm, e.g. [76, 130]
DPI	Number	203/300/600	-	Printer DPI; default 203
DIRECTION	Number	0/1	0	0: normal; 1: rotate 180°
DENSITY	Number	1-15	8	Print density (1 lightest, 15 darkest)
SPEED	Number	1-10	5	Print speed (1 slowest, 10 fastest)
SOUND	Number	0-10	0	Beep count after print (0 = none)
COPIES	Number	1-999	1	Copies per page
GAP	Number	0-10	2	Gap height in mm; set 0 for continuous paper
BLACKMARK	Number	0-10	0	Black-mark height in mm; mutually exclusive with GAP (BLACKMARK preferred)
OFFSET	Array	[x, y]	[0, 0]	Print origin offset in mm
CUT	Number	0/1/2	0	0: no cut; 1: full cut; 2: half cut
PEEL	Number	0/1	0	0: off; 1: peel on
REWIND	Number	0/1/2	0	0: off; 1: rewind forward; 2: rewind reverse
REWIND_OFFSET	Number	0-100	0	Reverse rewind offset in mm; required when REWIND=2
FEED	Number	0-100	0	Extra feed after print in mm
LANGUAGE	String	TSPL/CPCL	-	Force target print language; if omitted, auto-detect (default TSPL)

Common element attributes

label array elements share these common attributes. Coordinates are in dots; origin is top-left.

Attribute	Type	Range	Default	Notes
type	String	See element types	-	Print element type, required
x	Number	≥0	0	Horizontal start coordinate in dots
y	Number	≥0	0	Vertical start coordinate in dots
cont	String	-	-	Print content, required (except graphic elements)
r	Number	0/90/180/270	0	Rotation angle clockwise

Element types & specific attributes

Text (TEXT)

font maps to TSPL TEXT x,y,"font",rotation,x-multiplication,y-multiplication,"content" font-type parameter. In JSON it must be a string, e.g. "font":"1". Font IDs are not limited to digits; you may use Chinese font names or model-specific fonts supported by the device firmware.

Attribute	Type	Values	Default	Notes
font	String	Printer-supported font ID	"0"	TSPL TEXT font type: built-in, Chinese, or custom; actual values depend on the device
w / h	Number	0-15	0	Width/height magnification (0=1×); range may vary by model
bold	Boolean	true/false	false	Bold
underline	Boolean	true/false	false	Underline
reverse	Boolean	true/false	false	Inverse (white on black)
spacing	Number	0-10	0	Character spacing in dots

Barcode

Supported types: BC128、CODE39、EAN13、EAN8、UPC-A、UPC-E、CODE93、ITF、MSI、CODABAR

Attribute	Type	Values	Default	Notes
h	Number	≥0	30	Barcode height in dots
show	Number	0/1/2	1	0: hide HRI; 1: below; 2: above
narrow	Number	1-6	1	Narrow bar width in dots
wide	Number	1-10	2	Wide bar width; CODE128 fixed to 1
checksum	Boolean	true/false	true	Auto checksum

QR code

Supported types: QRCODE、PDF417、DATAMATRIX

Attribute	Applies to	Notes
e	QRCODE	Error correction L/M/Q/H; default M
w	QRCODE	Module width 1–10 dots; default 4
version / mask	QRCODE	Version 1–40 (0=auto); mask 0–7 (-1=auto)
w / h	PDF417	Module width/height 1–10 dots; default 2
w / e	DATAMATRIX	Module width 1–10; ECC level 0–8, default 2

Graphics

Supported types: BAR (line)、RECT (rectangle)、ROUNDRECT (rounded rectangle)、CIRCLE (circle)、ELLIPSE (ellipse)

Attribute	Notes
w	Width/length in dots; BAR = line length, CIRCLE = diameter
h	Height/line width in dots; not needed for CIRCLE
r	Corner radius in dots (ROUNDRECT only)
fill	Fill shape; default false

Bitmap (BITMAP)

Attribute	Notes
cont	Base64 1-bit BMP/PNG data, or HTTP/HTTPS image URL
w / h	Scaled width/height in dots; one value keeps aspect ratio
mode	NORMAL / INVERT; default NORMAL
dither	Enable dithering for grayscale; default true

DPI auto-conversion rules

Global fields in mm (SIZE, GAP, BLACKMARK, OFFSET, FEED, REWIND_OFFSET) auto-convert to dots by target DPI; element x/y stay in dots.

DPI	≈ dots per 1mm	Notes
203	≈8	Industry standard approximation
300	≈12	High-precision desktop printer
600	≈24	Industrial high-precision printer

Images scale by target DPI to avoid blur or stretch
Barcode/QR module width adapts to DPI for scannability
label may be a 1D array (single label) or a 2D array (multiple different labels in one job); use COPIES for identical reprints

JSON · 40×30mm · single

{
  "SIZE": [40, 30],
  "DIRECTION": 1,
  "DENSITY": 15,
  "label": [
    {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     Dine-in-2    1/5"},
    {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "Guava smoothie boba     "},
    {"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": "SW BBQ House (Outlet A)"}
  ]
}

Set label to a 2D array; each outer sub-array is one label. Print several distinct labels in one job (e.g. cup stickers 1/5–5/5).

JSON · 40×30mm · 5 different labels

{
  "SIZE": [40, 30],
  "DIRECTION": 1,
  "DENSITY": 15,
  "label": [
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     Dine-in-2    1/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "Guava smoothie boba     "},
      {"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": "SW BBQ House (Outlet A)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     Dine-in-2    2/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "Guava smoothie boba     "},
      {"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": "SW BBQ House (Outlet A)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     Dine-in-2    3/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "Guava smoothie boba     "},
      {"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": "SW BBQ House (Outlet A)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     Dine-in-2    4/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "Pineapple smoothie      "},
      {"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": "SW BBQ House (Outlet A)"}
    ],
    [
      {"type": "TEXT", "x": 5, "y": 10, "w": 1, "h": 2, "r": 0, "cont": "#82     Dine-in-2    5/5"},
      {"type": "TEXT", "x": 5, "y": 55, "w": 1, "h": 2, "r": 0, "cont": "Guava milk tea          "},
      {"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": "SW BBQ House (Outlet A)"}
    ]
  ]
}

Global XML vector layout

This spec uses the printer built-in multilingual vector font library for smart layout (e.g. tables), vector font scaling by size, mixed-language print (including Uyghur, Mongolian, etc.), and UTF-8 content without code-page switching. Versus graphic printing: simpler development and smaller payloads — ideal for Bluetooth and mobile networks.

XML layout under this spec supports label and ticket modes: labels have fixed width/height with per-element x/y; tickets are thermal receipt stream layout with multi-column tables and auto wrap.

Spec version: v1.7

Encoding: UTF-8

API push: Print job type set to 4 (XML); Base64-encode the layout into message field

Note: attributes with defaults may be omitted. Coordinates are in dots; at 203 DPI, 1mm≈8 dots (58mm ≈384 dots, 80mm ≈576 dots).

1. Label layout (root node label)

Object	Attribute	Notes
label	width / height	Label width/height in mm
	dpi	Print DPI; default 203
	direction	Print direction: 0 (default) or 1
	density	Density 1–15; default 8
	gap	Label gap; default 2mm
	language	Command language: tspl (default), cpcl, ezpl
	copy	Copies; default 1

text (label text; requires x/y)

Attribute	Notes
x / y	Top-left coordinates in dots
font	Font size 8–100; larger = bigger text
align	left / center / right
bold	0 not bold (default), 1 bold
width	Max text width in dots; wraps when exceeded
dir	rtl right-to-left; ltr left-to-right
strike	Whole-run strikethrough: 0 off (default); 1 / true / on
underline	Whole-run underline: 0 off (default); 1 single; 2 double
decoration	CSS-style combo, e.g. `line-through underline` (see Text decoration below)
reverse	Inverse (white on black): 0 normal (default); 1 on; can combine with bold / strike / underline

barcode / qrcode (label; requires x/y)

Object	Attribute	Notes
barcode	x, y, height, type (BC128, etc.), hrt (0/1 show HRI)	1D barcode
qrcode	x, y, size (1–10, default 2), ecc (1=L/2=M/3=Q/4=H)	QR code

line / img / graphics (label)

Object	Attribute	Notes
line	x, y, end_x, end_y, width	Line
img	x, y; content is URL or Base64	PNG/BMP raster image
rect	x, y, w, h, fill (0/1), width (stroke)	Rectangle
roundrect	x, y, w, h, r (radius), fill, width	Rounded rectangle
circle	x, y, r (radius), fill, width	Circle
ellipse	x, y, w, h, fill	Ellipse

2. Receipt layout (root node receipt)

Object	Attribute	Notes
receipt	width	Receipt width in dots; 58mm≈384, 80mm≈576
	font	Global font size 8–100
	dir	Global text direction rtl / ltr

text (receipt text; auto wrap)

Attribute	Notes
align / bold / font / dir	Same as label text; no x/y needed
strike / underline / decoration / reverse	Same as label text; see Text decoration below

table / tr / td (multi-column)

Supports: two-column L/R align, multi-column ratio wrap, inline barcode/QR/image, bordered tables.

Object	Attribute	Notes
table	border	0 no border; >0 border width in dots
table	div_line	Dashed divider height (mutually exclusive with border)
table	font / dir	Table-wide font size and direction
tr	—	One row containing td
td	width	Column width: %30 etc., or absolute dots (one style per table)
td	align / bold / font	Per-cell settings; may nest barcode, qrcode, img
td	strike / underline / decoration / reverse	Text-cell decoration; same semantics as text (see below)

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

Object	Main attributes	Notes
barcode	type, height, readable, align	Receipt barcode; readable 0/1 show HRI
qrcode	align, size (1–10), ecc (1–4)	Receipt QR code
img	align, src/content, width, height	png/jpg/bmp; URL or Base64
space	Number / value	Blank line height in dots, e.g. <space>20</space>
line	x, end_x, width, dash, font	Divider line; may include centered text
cut	—	<cut></cut> cutter
cash / plugin	—	Open cash drawer

Appendix: barcode types & image syntax

No.	Type	Alias	Notes
1	CODE128	BC128	Default 1D barcode
2	CODE39	BC39	Code 39
3–9	CODE93, EAN13, EAN8, UPCA, UPCE, ITF, CODABAR	I25, etc.	Common retail/logistics barcodes
10–16	QRCODE, PDF417, DATAMATRIX, AZTEC, MAXICODE, MICROQR, HANXIN	—	2D codes (type name uppercase)

Image syntax

img supports three forms; receipt layout may use align for alignment; label layout needs x、y coordinates.

Method 1 URL as element content

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

Method 2 URL via src attribute

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

Method 3 Inline Base64; optional width/height

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

3. Text decoration & inline styles (v1.7)

Applies to vector XML <text> (label / receipt) and table text cells <td>. Decoration follow glyphs across wrap, multilingual text, and RTL. Omitting attributes keeps v1.6 behavior.

Whole-run attributes

Attribute	Values	Notes
strike	0 / false / off (default); 1 / true / on / single / line-through	Whole-run single strikethrough through mid-glyphs
underline	0 (default); 1 / single; 2 / double	Whole-run underline
decoration	Space-separated keywords, e.g. `line-through underline`	CSS-style combo: `line-through`/`strike` enables strikethrough; `underline` single underline; `none` disables. Prefer strike / underline for whole-run styles
reverse	0 (default); 1 / true / on / reverse / invert	Inverse: black box behind glyphs, white text (not full-line fill). Can combine with bold, strike, underline, dir="rtl". Prefer titles / emphasis lines to save ink

Inline tags (partial styles)

Place inside <text> / <td> content; only the wrapped substring is styled. Do not use as top-level print items. Content buffer limit: 1024 bytes (including inline markup).

Tag	Notes
<s>…</s>	Partial strikethrough (recommended)
<del>…</del> / <strike>…</strike>	Strikethrough aliases (same as <s>)
<u>…</u>	Partial underline
<b>…</b> / <i>…</i>	Partial bold / italic
<span>, <tt>, <big>, <small>, <sub>, <sup>	Pango markup subset (advanced; use with care)

Usage notes

Label layout uses <label> root; receipt layout uses <receipt>
Do not mix with simple XML layout (<BR>, <CB>, etc.) — two separate syntaxes
Within one table, use either percentages or dots consistently

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">Text size 8</text>
    <text font="48" align="center" bold="1">Title size 48</text>
    <text font="72" align="center" bold="1">Title size 72</text>
    <line dash="8" width="3" font="18">Divider</line>
    <table>
        <tr>
            <td align="left">Column 1</td>
            <td align="right" font="36" bold="1">Column 2</td>
        </tr>
    </table>
    <table border="1">
        <tr>
            <td width="%30">Header 1</td>
            <td width="%40">Header 2</td>
            <td width="%30">Header 3</td>
        </tr>
        <tr><td>Cell 1-1</td><td>Cell 1-2</td><td>Cell 1-3</td></tr>
        <tr><td>Cell 2-1</td><td>Cell 2-2</td><td>Cell 2-3</td></tr>
    </table>
    <space>30</space>
    <table>
        <tr>
            <td width="%50">Text beside QR</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">Multilingual vector print</text>
    <text font="8" align="center">Font size 8</text>
    <text font="64" align="center">Font size 64</text>
    <table>
        <tr><td width="%30">English</td><td width="%70">Multilingual tests for thermal printers</td></tr>
        <tr><td>Chinese (Simplified)</td><td>热敏打印机多语言测试</td></tr>
        <tr><td>Chinese (Traditional)</td><td>熱敏打印機多語言測試</td></tr>
        <tr><td>Japanese</td><td>サーマルプリンタの多言語テスト</td></tr>
        <tr><td>Korean</td><td>열감 프린터 다국어 테스트</td></tr>
        <tr><td>Arabic / Uyghur</td><td>قاراپايدار چاپقۇچى</td></tr>
        <tr><td>Mongolian</td><td>Өгтгөлтөрөгч олон хэл тест</td></tr>
        <tr><td>German</td><td>Mehrsprachige Tests für Thermoprintern</td></tr>
        <tr><td>Thai</td><td>ทดสอบภาษามายากสำหรับเครื่องพิมพ์ความร้อน</td></tr>
        <tr><td>Vietnamese</td><td>Kiểm tra đa ngôn ngữ cho máy in nhiệt</td></tr>
    </table>
    <table>
        <tr>
            <td width="%50">Text beside QR / barcode</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 text decoration

<receipt width="576">
    <text align="left" strike="1">Whole-line strike: VOID line ABC 123</text>
    <text align="left" underline="1">Whole-line underline: Total amount</text>
    <text align="left" decoration="line-through underline">Strike + underline</text>
    <text align="left" underline="2">Double underline: Amount due</text>
    <text align="center" font="28" bold="1" reverse="1">RETURN SLIP</text>
    <text align="left" reverse="1" underline="1">Reverse + underline</text>
    <text align="left">Was <s>$100.00</s> Now $80.00</text>
    <text align="left">Cancelled: <del>Americano x1</del></text>
    <table>
        <tr>
            <td width="%50" strike="1">Returned item</td>
            <td width="%50" align="right" strike="1">$12.00</td>
        </tr>
        <tr>
            <td width="%50" reverse="1">Reverse cell</td>
            <td width="%50" align="right">$8.00</td>
        </tr>
    </table>
    <cut></cut>
</receipt>

<!-- Label mode supports the same styles -->
<label width="50" height="30" dpi="203">
    <text x="10" y="20" font="24" strike="1">VOID</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">Text line size 8</text>
    <text font="48" align="center" bold="1">Title size 48</text>
    <text font="72" align="center" bold="1">Title size 72</text>
    <line dash="8" width="3" font="18">Divider</line>
    <table>
        <tr>
            <td align="left">Column 1</td>
            <td align="right" font="36" bold="1">Column 2</td>
        </tr>
    </table>
    <table border="1">
        <tr>
            <td width="%30">Header 1</td>
            <td width="%40">Header 2</td>
            <td width="%30">Header 3</td>
        </tr>
        <tr><td>Cell 1-1</td><td>Cell 1-2</td><td>Cell 1-3</td></tr>
        <tr><td>Cell 2-1</td><td>Cell 2-2</td><td>Cell 2-3</td></tr>
        <tr>
            <td>Cell 3-1</td>
            <td>Cell 3-2, wraps automatically</td>
            <td>Cell 3-3, wraps automatically</td>
        </tr>
    </table>
    <space>30</space>
    <line dash="8" width="3" font="18">Divider</line>
    <table space="10">
        <tr>
            <td width="%50">Text beside image or barcode; wraps automatically</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">http://example.com/logo.png</img>
    <cut></cut>
</receipt>

Simple XML layout

Compatible with common simple XML layouts used by other vendors:

Tag	Notes	Remarks
<BR>	Line break	Every line must end with a line break
<CUT>	Cutter command	Effective on models with a cutter
<IMG></IMG>	Bitmap image Base64	8-bit grayscale only; Base64 size ≤ 6KB
<PLUGIN>	Open cash drawer	Effective on models with cash-drawer port
<CB></CB>	Scale ×2 and center	Applies to characters
<B></B>	Scale ×2	Applies to characters
<L></L>	Double height	Applies to characters
<W></W>	Double width	Applies to characters
<QR></QR>	QR code	One QR code per receipt Max 256 characters Size via <QR:n></QR>; n default 5, range 1–15
<C></C>	Center line content	Default left align when <C> / <RIGHT> are omitted
<RIGHT></RIGHT>	Right-align line content
<BOLD></BOLD>	Bold text
<BC128></BC128>	CODE128 barcode	Up to 14 digits and uppercase letters
<BC128_A></BC128_A>	CODE128 barcode	Up to 14 digits and uppercase letters
<BC128_C></BC128_C>	CODE128 barcode	Up to 22 digits only

Layout format recommendations

JSON: Structured data for complex layouts and dynamic generation; ticket and label modes; supported on all cloud print devices
Vector XML: Uses built-in vector fonts; root <label> (label coordinate layout) or <receipt> (receipt stream layout); global languages, any font size, graphics — for M-series multilingual models
Simple XML: Compatible with other vendors' <BR>, <CB> tags; simple receipts; all receipt printers

Quickstart

First print in 5 minutes

Fast integration

Online debug

Singapore Open API (fixed signature)

Label layout (JSON)

Protocol

Supported printer types

Protocol rules

Print content layout

Workflow

API

Fixed-signature APIs

Common rules:

Bind printer API debug

Unbind printer API debug

Text print push API debug

Voice broadcast push API debug

Get device info API debug

Clear print queue API debug

Device status & print result callback

Device status / job result callback

Endpoint & parameters

Response parameters

Device & job status codes

Device & API status codes

1. Device network status (when querying device info)

2. Device status codes (print push, device info query, callbacks)

3. API access status (when pushing print jobs)

4. Print API operation status (inner code only when HTTP access status is 200)

5. Print result status codes (portal or callbacks)

Print layout

JSON ticket layout

JSON label layout

Global label parameters

Common element attributes

Element types & specific attributes

Text (TEXT)

Barcode

QR code

Graphics

Bitmap (BITMAP)

DPI auto-conversion rules

Global XML vector layout

1. Label layout (root node label)

text (label text; requires x/y)

barcode / qrcode (label; requires x/y)

line / img / graphics (label)

2. Receipt layout (root node receipt)

text (receipt text; auto wrap)

table / tr / td (multi-column)

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

Appendix: barcode types & image syntax

Image syntax

3. Text decoration & inline styles (v1.7)

Whole-run attributes

Inline tags (partial styles)

Simple XML layout

Layout format recommendations