Serve the document to print with the BizPrint Print API (print by URL)

This page explains how to serve the document you want to print, at the url you send when you create a print job with the BizPrint Print API. It is for developers, and it covers both kinds of station: the BizPrint desktop app and the BizPrint Android app. A PDF works on both.

How printing by URL works

You do not upload a file to BizPrint. Instead, you send a web address:

Your server creates a print job with a url, such as https://example.com/receipts/1001.pdf?token=LONG_RANDOM_TOKEN. See Create a print job with the BizPrint Print API.
BizPrint sends the job to the station that the printer belongs to.
The station downloads the address itself.
The station prints what it downloaded and reports the result.

Because the station downloads the document at print time, your page must still work when the station gets to the job. A reprint from the BizPrint dashboard downloads the same address again, so it prints the document as it is at that moment.

Make the address reachable from the station

Use a full address the station can reach. The station loads the address from its own network, so the address must work on the station’s computer or device. Use https:// where you can.
Do not use localhost for your server. On the station, localhost means the station’s own computer or device, not your server.
Do not require a sign-in. The station has no session or cookies for your site. If the page asks for a login, the station prints the login page or the job fails.
Protect the page with a long, random token in the address instead, so the station can load it but nobody can guess it. Treat the full address as private.
Keep the address working for as long as you might reprint the job. If the token expires or the page is deleted, a reprint cannot load it.
Return the document with a success status. If your server returns an error page instead of your document, the station cannot print your document.
Ignore query parameters you do not use. The station may request your address with extra query parameters added. Your page should still load normally when that happens.

What to serve for each station

Station	What it prints	What to serve
BizPrint desktop app (Windows, Mac or Linux)	PDF files	A PDF
BizPrint Android app	PDF, HTML and plain text documents, and ZPL or TSPL label code on label printers	A PDF, an HTML page, plain text, or label code in the printer’s language

Desktop app: PDF

The desktop app prints through the computer’s own printer drivers. Send it PDF documents.

Serve the file with the content type application/pdf.
Make sure your server answers HEAD requests for the address with the same content type. The desktop app checks the content type before it downloads, by asking your server for the headers only (a HEAD request). If the answer is not application/pdf, the desktop app treats the file as a web page, and it may not print.
Size the PDF pages for the paper they print on, for example a narrow receipt width.

Android app: PDF, HTML or plain text

The Android app prints PDF, HTML and plain text documents on receipt printers, label printers, full-page office printers and the built-in printer of Sunmi devices. It decides what the document is from the downloaded content and its content type, not from the address. Label printers can also print ZPL or TSPL label code. See Android app: ZPL or TSPL label code.

PDF: serve the file with the content type application/pdf, or make sure the file starts with %PDF-. Each PDF page prints as its own page. A PDF can have up to 200 pages, and it must not be password protected.
HTML: serve a web page. The app lays it out at the paper width set for the printer in the app, with images and your styles. Images and other files with relative addresses load from your page’s address. Scripts on the page run before printing, unless the printer’s settings in the app turn them off.
Plain text: serve the text with the content type text/plain, with line breaks where you want new lines. You can also wrap the whole text in one <pre> and </pre> pair, which the app removes before it prints. On a receipt printer, plain text prints with the printer’s own fonts. Keep lines short, because receipt paper is narrow.
Labels: for a label printer, serve a PDF or an HTML page sized for one label, or label code in the printer’s language.
Size and time: keep the document under 20 MB, and make sure your server sends it within 30 seconds.

The paper size comes from the printer’s settings in the Android app, so design the document to fit that paper. See Change paper, cut and layout settings for a printer in the BizPrint Android app.

If you send jobs to both kinds of station, a PDF works on both. For the differences between the two apps, see Desktop app or Android app: which BizPrint station should you use?.

Android app: ZPL or TSPL label code

A label printer on an Android station can print ZPL or TSPL label code that you already have, such as a shipping label from your shipping software.

Match the printer language. Send ZPL code to a printer whose Printer language in the app is ZPL, and TSPL code to a printer whose Printer language is TSPL. On any other printer, including receipt printers, full-page office printers and the built-in printer of Sunmi devices, the job fails with “This job is ZPL label code. Send it to a ZPL label printer.” or “This job is TSPL label code. Send it to a TSPL label printer.”
Serve the code as text. Use a content type such as text/plain, not application/pdf. The station recognises label code from the content it downloads, not from the address or a file extension.
ZPL: the document starts with a ZPL command (^ or ~, such as ^XA) or with CT~~, after any spaces or blank lines, and contains a label that starts with ^XA and ends with ^XZ.
TSPL: the document starts with setup commands, such as SIZE, GAP or CLS. A drawing command at an x,y position follows, such as TEXT 10,10,... or BARCODE 10,10,..., and then a PRINT line. Blank lines and REM comments can go anywhere before the drawing command.
Commands can be upper or lower case.
Wrapping: you can wrap the whole code in one <pre> and </pre> pair. The station removes that pair, any whitespace outside it, and a byte order mark just before or inside it. It keeps every other byte.
Sent unchanged: the station sends the code to the printer exactly as it is and adds no commands. The printer’s paper and label settings in the Android app do not change it, so put the label size, darkness and speed in your code or set them on the printer.
Copies: the station sends the code once for each copy of the job.
Desktop stations print PDF documents. For a label printer on a desktop station, send a PDF label.

A ZPL label:

^XA
^FO50,50^ADN,36,20^FDOrder 1001^FS
^XZ

A TSPL label:

SIZE 4,6
GAP 0.12,0
CLS
TEXT 10,10,"3",0,1,1,"Order 1001"
PRINT 1

Test your page

Open the address in a private browser window on the station’s computer or device.
Check that it loads without a sign-in and shows exactly what you want printed.
Turn on Development Mode in the BizPrint dashboard while you test. On a desktop station, printouts in Development Mode are marked, so staff can tell them apart from real ones. See Test printing with Development Mode in the BizPrint dashboard.
Create one print job with the address, to a printer you can see.
Look at the printout at the printer.
Check the job’s status. See Check print job status with the BizPrint Print API.
Turn Development Mode off when you finish testing.

If the job fails

If the station cannot download or print your page, the job’s status becomes failed. Fix the page first. Then do these checks before anything prints again, because every new job prints again:

Look at the paper at the printer for that document.
Check the job’s status in the BizPrint dashboard, or with the Print API.
Let the station finish what it is printing, whatever status the job shows.
Do nothing more while the job is still pending, connecting-to-printer or processing.
Reprint the existing job from the dashboard, instead of creating a new one, only if it really did not print. The reprint goes to the printer the job was first sent to and downloads your fixed page. See Reprint a print job from the BizPrint dashboard.

Never create a new job in a loop until one works. Do not re-send a create request after a timeout without first looking up whether the job was created.

Need help? Contact BizPrint support at https://getbizprint.com/support/.