How to use the Barcode Printing API¶

This section covers the usage of the Barcode Printing API. It would discuss the authentication and authorisation strategy, accepted payload, response sent and error codes that the clients can expect.

Authentication & Authorisation Strategy¶

Like for many integrations that the Integration Hub provide, the Barcode Printing integration require (at the time of this writing) client-credentials based OAuth 2.0 authentication. OAuth 2.0 is a standard authentication strategy that takes in a credential pair and uses a token-based validation scheme for authorisation.

Info

The token used in this scheme is a JSON Web Token (JWT).

Hence, each request that the client sends would need to be authenticated as per the authentication scheme. If authorised, the client would get access to the API which is a protected resource sitting behind a token validator.

Obtaining the client credentials need to be done by raising a FreshService ticket. Displayed below is the OAuth 2.0 procedure for authorisation and authentication.

sequenceDiagram
    autonumber

    participant Client
    participant AS as Authorization Server
    participant RO as Resource Owner
    participant RS as Resource Server

    Client->>AS: Authorization Request

    AS->>AS: Authenticate Client & Validate requested scopes

    RO->>AS: Grant access / consent

    AS-->>Client: Return access token

    Client->>RS: Request protected resource using access token (as per the protocol)

    RS-->>Client: Return protected resource

The details underlying the authentication providers are out of scope of this document.

The Payload¶

The Barcode Printing Integration requires the following data in its POST /barcodes HTTP REST endpoint:

Key	Description
`printer_name`	The name of the printer. This should be one of the available printers.
`label_template_name`	Each print job takes in a template and arguments to populate the template with. The template, however, is defined at the barcode printing provider level; the Integration Hub does not maintain the label tempaltes at the moment. This value, therefore is the name of the label template located in the provider.
`labels`	These are the arguments required to render the label template.
`copies`	The number of copies required of the label.

Warning

It is advisable for the users to go throught the "Example Use Cases" section to get a better grasp on the details listed above. There are some intricacies related to the arguments populated into the labels and the label_template_name which are discussed there.

Responses and error codes¶

The response codes returned by the Barcode Printing API are standard HTTP response codes. For a successful printing job submission to the provider, the API would return a 200, while the following error codes would return for different error scenarios:

200: Successful response. The response schema is depicted in the "API documentation".
40X: This error code identifies an error in the request submitted. When it is an error caught by the integration hub (i.e., a validation error), the error would be returned with error messages generated by the Integration Hub. If and when the error is not caught by the API, but was caught by the provider itself, the message would be wrapped (please check the API documentation for the schema of the response) in a details block.
50X: This error code identifies a server-side error. It could be the case that the Barcode Printing API cannot be reached by the client, or an internal server error. The schema for this is depicted in the API documentation.