Scanning

Overview and Usage

The Scanning API is also a RESTful endpoint residing on the target terminal, however it consists solely of GET requests with appropriate parameters as detailed below. Furthermore, the API is intended to capture barcode and QR code data ONLY and will return this data as a Base64 encoded string.

The following barcodes/QR codes are supported:

Supported Barcode Formats

• UPC-A
• UPC-E
• EAN-8
• EAN-13
• Code 39
• Code 128
• Interleved 2 of 5
• Codabar
• MSI

Supported QR Code Formats

• QR Code
• Data Matrix
• PDF417
• Aztec Code
• MaxiCode

---

GET/scan Request

URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/scan

LOCAL HOST

If you are sending the GET/scan request from the device you want to trigger the barcode scanning on, you can use local host 127.0.0.1 to send the request to.

An HTTPS GET request should be sent to the above URL with the following parameters:

POST /scan - Query String Parameters
Field Name	State	Data Type	Description
tid	Mandatory	String	This is the Serial Number of the terminal that should print the request. This is printed on a label on the rear of the device.
preferBarcodeScanner	Optional	Boolean	Determines whether the scan request will use the on-board barcode scanner if one is present, if not the request will default to using the on-board rear-facing camera. Set to true to use the barcode scanner. Default = false.
preferFrontCamera	Optional	Boolean	Determines whether the scanner should use the Front Camera if one is present, if not the request will default to using the on-board rear-facing camera. Set to true to use the front-facing camera. Default = false.
timeoutSec	Optional	Integer	Determines how long, in seconds, to wait for the scan request to succeed or be cancelled, after which the request will time out. If this parameter is omitted then a default of 60 seconds is used.
POST /transaction - Header Parameters
Authorization	Mandatory	String	This field should be populated with a value of Bearer 6945595921271780

REQUEST BODY

There are no required parameters for the request body, this can be left empty.

Example Requests

Request with Barcode Scanner

Request sent with the intention of using the Barcode Scanner (if available) with a timeout of 20 seconds.

GET https://127.0.0.1:8080/POSitiveWebLink/1.1.0/rest/scan?tid=1760011990&preferBarcodeScanner=true&timeoutSec=20

Request with Rear Camera

Request sent with the intention of using the Rear Facing Camera with a timeout of 10 seconds.

GET https://127.0.0.1:8080/POSitiveWebLink/1.1.0/rest/scan?tid=1760011990&preferFrontCamera=false&timeoutSec=10

Request with Front Camera

Request sent with the intention of using the Front Facing Camera with the timeoutSec parameter omitted.

GET https://127.0.0.1:8080/POSitiveWebLink/1.1.0/rest/scan?tid=1760011990&preferFrontCamera=true

Parameter Usage

The preferBarcodeScanner and preferFrontCamera can be used in conjunction with each other so you can build your integration to accomodate different devices. For example if you set preferBarcodeScanner=true and preferFrontCamera=true in the same query string then the request will prioritise the barcode scanner if available, if not it will fallback to the camera but will prioritise the front facing camera. In the event a front facing camera is also not present the request will simply default to the rear facing camera.

---

GET/scan Response

When receiving a HTTPS GET response, you will receive one of two possible responses:

HTTP Response Code	Description
200	A scan request was successfully received by axept PRO with the body of the response containing the scan results. The details of the response body contents are detailed in the Example Responses below.
206	Transaction in progress This indicates that the scan request was made whilst the device was processing a transaction. The response body should be empty.

If properly formatted, you will receive a 200 HTTP response with the following fields:

GET /scan - 200 Response
Field Name	Data Type	Description
resultCode	Integer	The outcome of a successful Scan attempt. Can be one of the following values: 1 Success 2 Timeout 3 Cancelled
data	String	The captured data result from the barcode scan. If a resultCode of 1 is returned, you will get a Base64 encoded barcode/QR result. Otherwise when a resultCode of 2 or 3 is returned, this field will be "null".

Example Responses

Successful QR Code

{
    "resultCode": 1,
    "data": "aHR0cHM6Ly9kZXZlbG9wZXIuZG5hcGF5bWVudHMuY29tLw=="
}

Successful Barcode

{
    "resultCode": 1,
    "data": "MTIzNDU2Nzg5MTAxOQ=="
}

Timeout

{
    "resultCode": 2,
    "data": "null"
}

Cancelled

{
    "resultCode": 3,
    "data": "null"
}

Remember

Both QR codes and Barcodes are returned as base64 encoded strings.

---