Printing Labels & Documents

Overview

The printing of labels and documents in MachShip is typically handled in three ways:

  1. MachShip generates the labels, and sends them to a printer in the warehouse via the MachShip Printer App
  2. MachShip generates the labels, and you download them to your system, and manage printing internally
  3. You generate the labels yourself - you may use your own barcodes, or those generated by MachShip

This guide will discuss how to do the first two options via the API.

Printing With The MachShip Printer App

Printing of item labels and documents is managed by MachShip using the MachShip printer app, and the printing rules you setup in our platform, known as printer configurations.

The setup is straightforward:

  • The printer app is installed on a warehouse computer with access to the label printer.
  • The printer is setup in MachShip and linked to the printer app
  • A printer configurations is created with a printer evaluation rules that determine where labels are sent in specific situations.

A couple of plain language examples of such rules would be:

  • "If a consignment is created for warehouse A, and is created by User B, then send 1 copy of the labels to Printer C".
  • "If a consignment is created for warehouse B, and has a printer token of "Desk1", then send 1 copy of labels to Printer "Desk 1".
  • "If a dangerous goods consignment is created for warehouse B, then send DG paperwork to "A4 Printer Main".

For a guide on how to setup the printer app, and printer rules - see our printer setup guide here.

Printing When Creating Consignments Via The API

When creating consignments via the MachShip API - you have three different ways to manage your label printing depending on when you need the labels in relation to creating the consignment.

1. Printer Token In API Request For Immediate Printing In your create consignment API request, you can input a unique "printer token" - any string - that can be used to steer printing.

Common printer tokens would be a username, email or desk id.

{
  ...
  "printerToken": "Desk1",
  ...
}
{
  ...
  "printerToken": "john@acmewarehousing.com.au"
  ...
}

You would then setup evaulation rules for each warehouse and each printer token to steer the printing to the correct printer.

A plain language version of such a rule to configured in MachShip would be:

  • "If a consignment is created for warehouse B, and has a printer token of "Desk1", then send 1 copy of labels to Printer "Desk 1 - Zebra Label Printer".

When you create a consignment via the API, it would immediately run that rule and send the labels to the relevant printer.

2. Trigger Printing Using A Second API Request You can trigger label printing programmatically using the /apiv2/labels/sendLabelsToPrinter endpoint. This gives you control over when and where labels print while still utilizing MachShip's printer infrastructure.

Your API request to trigger printing would be:

POST https://live.machship.com/apiv2/labels/sendLabelsToPrinter HTTP/1.1
Host: live.machship.com
token: <api_token>
body: 
[
  {
    "consignmentIds": [
      1234
    ],
    "labelType": 3, //3 is the item labels
    "printerId": 0, //id of your printer in Machship
    "printA4": false
  }
]

You will only need to do this if you create consignments prior to you needing the labels. If you want the labels to print immediately on consignment creation, you can use the printer token method.

3. UI-Based Printing Users can leverage MachShip's interface to search, filter, and bulk print labels as needed. This is particularly useful for batch processing or when manual intervention is preferred.

Using this method, you will not need to make any changes to your API requests.

The user would select a bunch of consignments, then click "send to printer" and select a pre-configured printer to send the labels to.

3. Download Labels, & Print Internally If you need complete control over the printing process, you can retrieve label PDFs through the /apiv2/labels/getItemPdfFileInfo endpoint and manage printing entirely within your system.

The fields on the request are: consignmentId - that's the 'id' returned in the response after you create the consignment printA4 - by default, our labels print in A6 - but if you need them in a4, you can set this to true

GET https://live.machship.com/apiv2/labels/getItemPdfFileInfo?consignmentId=1234&printA4=false HTTP/1.1
Host: live.machship.com
token: <api_token>

Response:

{
  "object": {
    "fileName": "CON1234.pdf",
    "contentType": "application/pdf",
    "content": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9...." //base64string
  }
}

You would decode the base64 string, and save it to a file and that file would be a PDF of the labels for all items on the consignment.

Printing When Creating Pending Consignments Via The API

For pending consignments, you will not need to make any specific API calls or adjustments to your requests to manage or steer labels to specific printers.

The reason for this is that pending consignments must be created/converted into a consignment by a user inside the MachShip platform.

Given that, any and all printing rules can be linked to the warehouse AND user, rather than the consignment request itself - as it's that users action that needs to trigger printing.

Here is a plain language implementation to explain:

  1. You create a pending consignment via the API - it has warehouse, to address, references set - but no packages or carrier yet.
  2. Warehouse user pick and pack the order
  3. Warehouse user opens the "Pending Consignment" screen and enters the SO order number (reference on the consignment) - and clicks on it
  4. They add the packages to the prefilled consignment, and select a carrier - then click CREATE CONSIGNMENT
  5. A printer rule is triggered: "If a consignment is created for warehouse A, and is created by User B, then send 1 copy of the labels to Printer C".
  6. The labels print on that users printer

Given this workflow, there is no requirement for you to make any changes to your API requests to facilitate this workflow.