Skip to content

Example use of the Barcode Printing API

The following section aims to give a brief example use case for barcode printing. The section does not go into an elaborate scenario as printing a barcode is very straight forward.

Scenario: print-my-barcode

Currently, the integration only supports integrating with print-my-barcode and sprint (which integrates via print-my-barcode). Therefore, this scenario is for a LIMS to use the integration to communicate with print-my-barcode and sprint.

Info

As mentioned before, this integration is meant to act as a "facade" for many barcode printing providers. As of this writing, since there is only the two printing services available, the integration supports only those two. In the future if and when multiple other barcode printing services arrive, the integration would internally use business logic to route the request to the appropriate barcode printing provider.

Assume that a client DEFBioLabs wants to print the label with a template traction_tube_label_template. The arguments given to the template are as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "barcode": "NT161514E-1",
  "first_line": "20-May-26",
  "second_line": "",
  "third_line": "NT161514E",
  "fourth_line": "1",
  "round_label_top_line": "NT",
  "round_label_bottom_line": "161514E",
  "round_label_lower_line": 1,
  "label_name": "main_label"
}

Warning

The integration that the Integration Hub provides does not try to render the template with arguments. This is a task for the underlying barcode printing provider (e.g., print-my-barcode). Therefore, in case there are invalid arguments provided, it is barcode printing provider's responsiblity to handle that and return with an appropriate response, which the integration would serialise into a harmonised response model.

However, the integration does validate essential arguments like printer_name, label_template_name which are crucial for printing barcodes. In a case where invalid data are provided to such attribtues, the integration would return a "Bad Request" response with proper error messages.

To achieve this, DEFBioLabs would need to:

  1. Authenticate with the Barcode Printing API.
  2. Prepare and send the payload to POST /barcodes endpoint of the integration.

Authenticating with the API

In order to authenticate, DEFBioLabs would have to follow the standard OAuth 2.0 protocol, as explained in "Authentication & Authorisation Strategy" section. Basically, the application of DEFBioLabs would need to invoke a /token endpoint and receive a token, and use the token in the headers to authorise with the POST /barcodes endpoint. To receive the token, the client would have to use the client credentials established as part of the onboarding process discussed in the "How to use" section.

Preparing the payload

In order to prepare the payload, DEFBioLabs would need to determine:

  1. Which printer they are going to use
  2. Which template they are going to use

These two points are dependent on each other. The printer they are going to use to print the label should be capable of printing the label according to the rendered template.

Also, the template and the printer should be valid; if the printer and/or the template is rejected by the barcode printing provider, the integration would respond with a "Bad Request" 400.

After DEFBioLabs has the aforementioned two points figured out, they can prepare the payload as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
    "printer_name": "printer-1",
    "label_template_name": "label_template_1",
    "labels": [
        {
            "barcode": "NT161514E-1",
            "first_line": "20-May-26",
            "second_line": "",
            "third_line": "NT161514E",
            "fourth_line": "1",
            "round_label_top_line": "NT",
            "round_label_bottom_line": "161514E",
            "round_label_lower_line": 1,
            "label_name": "main_label"
        }
    ],
    "copies": 1
}

Warning

In order for the client to be authorised to the POST /barcodes endpoint, the client needs to submit the above payload with the Bearer token received via the /token endpoint. This is again the standard OAuth 2.0 procedure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
curl --location 'https://ppd.integration-hub.sanger.ac.uk/barcodes/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer *** \
--data '{
    "printer_name": "printer-1",
    "label_template_name": "label_template_1",
    "labels": [
        {
            "barcode": "NT161514E-1",
            "first_line": "20-May-26",
            "second_line": "",
            "third_line": "NT161514E",
            "fourth_line": "1",
            "round_label_top_line": "NT",
            "round_label_bottom_line": "161514E",
            "round_label_lower_line": 1,
            "label_name": "main_label"
        }
    ],
    "copies": 1
}'

After the request has been submitted, the integration would return an OK 200.

Info

By receiving an OK 200 does not mean that the label was printed successfully by the printer. It merely means that the print job was successfully submitted and dispatched. It is now the barcode printing provider's responsibilty to communicate with the printer using the appropriate protocol and get the labels printed, which is beyond the scope of this integration.