Sign and check BizPrint Print API requests with the signing tool

This page shows you how to use the BizPrint signing tool, a small command-line program published on npm as @bizswoop/print-sign-request-cli. It is for developers who call the BizPrint Print API over plain HTTP and want to sign a request by hand, or check a signature that the API rejects.

The tool does the same signing as described in Sign BizPrint Print API requests. It is a help for testing and debugging. Your own server still signs the requests your app sends. If your server runs Node.js, it can sign them with the SDK. See Use the BizPrint Node.js SDK to create and check print jobs.

Before you start

• Install Node.js 20.19 or later on your own computer. The tool runs with npx, which comes with Node.js.
• Have the Public Key and Secret Key of an application that uses the REST API. See Get API keys for the BizPrint Print API.
• Run the tool only on a computer you trust. You type the Secret Key into the terminal and it shows on screen. Do not run it while you share your screen, and never paste the Secret Key into a ticket, chat or email.

Start the tool

1. Open a terminal.

2. Run this command:

   npx @bizswoop/print-sign-request-cli

3. Confirm the install if npx asks. The tool asks What do you want to do?

4. Use the arrow keys to choose one of the options.

5. Press Enter.

Option	What it does
Make a get request	Signs the query string for a GET request.
Make a post request	Signs a JSON body for a POST request.
Validate a get request	Checks the hash in a signed query string.
Validate a post request	Checks the hash in a signed JSON body.

Sign a GET request

1. Choose Make a get request.

2. Type your Public Key at Public key.

3. Type your Secret Key at Secret key.

4. Paste the request address, or only its query string, at Enter Request URL or query string. For example:

   https://print.bizswoop.app/api/connect-application/v1/printers?perPage=10&page=1

5. Answer Update time? with Yes (the default). The tool sets time to the current time.

6. Copy the query string the tool prints. It has your parameters plus publicKey, time and hash.

7. Send the request to the same path with that query string, for example https://print.bizswoop.app/api/connect-application/v1/printers? followed by the copied text.

Send the signed request within a few minutes. The API checks time and rejects requests that are too old. If you change any parameter after signing, sign it again.

Sign a POST request

1. Choose Make a post request.

2. Type your Public Key at Public key.

3. Type your Secret Key at Secret key.

4. Answer Update time? with Yes (the default).

5. Press Enter at Enter JSON payload. Your terminal’s default text editor opens. To use a different editor, set the EDITOR environment variable before you start the tool.

6. Type the JSON body, for example:

   {
     "printerId": YOUR_PRINTER_ID,
     "url": "https://example.com/receipts/1001.pdf?token=LONG_RANDOM_TOKEN",
     "description": "Order 1001"
   }

   Replace YOUR_PRINTER_ID with the ID of your printer, as a number without quotes.

7. Save the file.

8. Close the editor.

9. Copy the JSON the tool prints. It is your body plus publicKey, time and hash.

10. Send it as the body of the POST request, exactly as printed, with the header Content-Type: application/json.

Caution

Sending a signed POST /jobs body creates a new print job and prints it, every time you send it. Send it once. If you get no answer, do not send it again until you have done all of these checks:

• Look at the paper at the printer for that document.
• Look up your jobs with the API to see whether the job was created, and check its status. See Check print job status with the BizPrint Print API.
• Check the job’s status in the BizPrint dashboard.
• Wait for the station to finish anything it is still printing, whatever status the job shows.

Never send it again while the original job is pending, connecting-to-printer or processing.

Check a signature

Use the validate options when the API answers ERR_UNAUTHORIZED and you want to know whether the signature is the problem.

1. Choose Validate a get request or Validate a post request.
2. Type your Secret Key at Secret key.
3. Paste the signed query string or address for a get request, or paste the signed JSON body into the editor for a post request.
4. Save the file, if you used the editor.
5. Close the editor.
6. Read the result.

Result	What it means
Valid	The hash matches the rest of the request and your Secret Key. If the API still rejects it, check that the Public Key belongs to the same application and that time is recent.
Invalid (hash mismatch), expected … got …	The hash does not match. Common causes: the wrong Secret Key, or a parameter or field that changed after signing, including the order of the fields.
Invalid, missing arguments: …	The request is missing time, publicKey or hash.

You can also use Validate a post request to check a webhook body that BizPrint sent you, because webhooks are signed the same way. See Receive print job updates from BizPrint with webhooks.

Related pages

• Sign BizPrint Print API requests
• BizPrint Print API error codes and how to fix them
• Create a print job with the BizPrint Print API
• Receive print job updates from BizPrint with webhooks

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