Create a print job with the BizPrint Print API

This page shows you how to create a print job from your own app with the BizPrint Print API, and how to avoid printing the same thing twice. It is for developers who send print jobs from server code to a printer on a station running the BizPrint desktop app or the BizPrint Android app.

A print job does not carry the document. It carries a web address (URL). The station downloads the document from that address and prints it on the printer you choose.

Before you start

Get your application’s Public Key and Secret Key. See Get API keys for the BizPrint Print API.
Learn how to sign requests. See Sign BizPrint Print API requests. Keep the Secret Key on your server.
Find the ID of the printer you want to print to. See List printers with the BizPrint Print API.
Make the document available at a web address that the station can reach. See Serve the document to print with the BizPrint Print API (print by URL).

The request

Send a signed POST request to:

https://print.bizswoop.app/api/connect-application/v1/jobs

Send the body as JSON with the header Content-Type: application/json. Add publicKey, time and hash to the body, as described in Sign BizPrint Print API requests.

Property	Type	Required	What it is
`printerId`	number	Yes	The ID of the printer to print on.
`url`	string	Yes	The full web address of the document to print. It must be a valid URL.
`description`	string	Yes	A short text about the job, for example an order number. It appears in the Order column of the print jobs list in the BizPrint dashboard.
`printOption`	object, or a JSON string	No	Print options for the job. You can leave it out.

What the document can be depends on the station:

BizPrint desktop app: a PDF.
BizPrint Android app: a PDF, an HTML page or plain text. A label printer also prints ZPL or TSPL label code when its Printer language in the app is the same as the code. The station recognises label code from the document’s content, not from the address, and sends it to the printer unchanged, once for each copy.

A PDF works on both kinds of station. See Serve the document to print with the BizPrint Print API (print by URL).

The response

When BizPrint accepts the request, it answers with HTTP status 200 and a JSON object. Its data property is the new print job:

id: the job’s ID. Save it, so you can check the job later.
status: the job’s current print job status.
description, url and printerId: the values you sent.
createdAt and updatedAt: when the job was created and last changed.

Example in Node.js

This example uses Node.js 18 or later and reads the keys from environment variables. It creates one job and saves its ID. It does not retry on its own, because a retry can print the job twice.

import { createHash } from 'node:crypto';

const BASE_URL = 'https://print.bizswoop.app/api/connect-application/v1';
const publicKey = process.env.BIZPRINT_PUBLIC_KEY; // YOUR_PUBLIC_KEY
const secretKey = process.env.BIZPRINT_SECRET_KEY; // YOUR_SECRET_KEY, server only

export async function createPrintJob(printerId, url, description) {
  const body = {
    printerId, // YOUR_PRINTER_ID, as a number
    url, // for example 'https://example.com/receipts/1001.pdf'
    description, // for example 'Order 1001'
    publicKey,
    time: Math.floor(Date.now() / 1000),
  };
  const hash = createHash('sha256')
    .update(`${JSON.stringify(body)}:${secretKey}`)
    .digest('hex');

  const response = await fetch(`${BASE_URL}/jobs`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...body, hash }),
  });
  const result = await response.json();

  if (!response.ok) {
    // Read result.errorCode before you decide what to do.
    // See "If something goes wrong" on this page.
    throw Object.assign(new Error(result.message), {
      status: response.status,
      errorCode: result.errorCode,
    });
  }

  return result.data; // Save result.data.id with your order.
}

Never resend a print job blindly

Every request that BizPrint accepts creates a new print job, and every print job prints. If you send the same request twice, the printer prints twice.

If you get no answer (for example, the request timed out or the connection dropped), or you get a server error, BizPrint may still have created the job. Do not send the request again straight away. Check first:

Look at the paper at the printer. Make sure the document really did not print, and that the printer has paper and shows no error.
List your print jobs with a signed GET request to /jobs. Jobs are listed oldest first. See Check print job status with the BizPrint Print API.
Read the X-Biz-Total-Pages response header. It tells you the number of the last page, where the newest jobs are. See Page through results with the BizPrint Print API.
Request that last page.
Look for a job with your description and url.
Check the status of any matching job with GET /jobs/{id}, using its id. If the job is pending, connecting-to-printer or processing, do not create another one.
Check the job in the BizPrint dashboard, on the Print Jobs page for the printer.
Wait for the station to finish anything it is still printing, whatever status the job shows.
Send the request again only if no job was created and nothing printed. Send it once.

To make step 5 easy, give every job a description that is unique to it, such as your order number.

If something goes wrong

Every error answer has an errorCode and a message.

HTTP status	`errorCode`	What it means	What to do
400	`ERR_INVALID_REQUEST`	A property is missing or wrong. The `errors` property says which one and why.	Fix the request. No job was created, so you can send the corrected request.
400	`ERR_JOB_CREATING_PRINT_JOB_LIMIT`	Your account has reached its print limit.	No job was created. See https://getbizprint.com/pricing/ for plan details.
401	`ERR_UNAUTHORIZED`	The signature did not match, or the `time` value was not current.	Fix the signing. See Sign BizPrint Print API requests.
403	`ERR_JOB_CREATING_INVALID_PRINTER_ID`	The printer does not exist, or it is not on one of your stations.	List your printers and use one of their IDs.
403	`ERR_USER_IS_BLOCKED`	Your BizPrint account cannot create print jobs right now.	Contact BizPrint support.
500	`ERR_SOMETHING_WRONG`	Something went wrong at BizPrint.	The job may still exist. Do the checks in Never resend a print job blindly before you send it again.

For all error codes, see BizPrint Print API error codes and how to fix them.

After the job is created

BizPrint sends the job to the station, which downloads the document from your url and prints it. To follow the job:

Check its status with the API. See Check print job status with the BizPrint Print API.
Or let BizPrint tell your server with a webhook when the status changes. See Receive print job updates from BizPrint with webhooks.

If the station is offline, the job waits or is archived, depending on the Archive offline print jobs setting in the dashboard. See Choose what happens to BizPrint print jobs when a station is offline.

While you build and test, you can turn on Development Mode in the dashboard, so test printouts from desktop stations are marked as tests. See Test printing with Development Mode in the BizPrint dashboard.

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