Skip to main content

Getting Started

All Scantrust QR codes have a URL and contain a unique message to identify each code in the system. When the QR code is scanned by any QR code reader, the URL is opened, and the user is immediately redirected to the correct landing page.

Brand owners use the Scantrust Consumer Landing Page Editor to configure the default Scantrust landing pages, but in some cases, brands would like to design, build and host these landing pages themsevles. If this is the case, developers who would like to show information about the QR code need to call the Scantrust Consumer API from their landing page.

How a QR code is scanned

  1. The user opens their smartphone camera and scans a code.
  2. On iOS or Android, the phone the URL from the QR code is shown and the user is asked to open that link
  3. When the user opens the link, the scantrust scan-server identifies the code and determines which campaign the code is in.
  4. The scan-server creates a unique scan-id on the server with the details of the scan.
  5. Based on the campaign and the scan-id, the scan-server redirects the user to the landing page and passes in the scan_id in the URL
  6. The landing page uses this scan_id to fetch the information from the scantrust consumer API.
  7. The landing page displays the information associated with the scan (scan, code, company, campaign, scm data etc.)
  8. If the location was not set using GPS, the user is asked to opt in to share their location and the landing page calls the update location endpoint
  9. If a code is intended for consumption, the landing page can ask the user to mark the code as consumed

How to Use the Consumer API

All the scantrust APIs are REST API's and support JSON. We recommend to use a (free) tool called Postman to call this API for testing. The basic features of the Consumer API are:

  • Redirect the user to the correct landing page and generate a scan_id for data lookup

  • Show the Code Status, Authentication Results, Product and SCM data of the scan

  • Update the scan-location based on opt-in of the user to share their location (API details)

  • Set the code as consumed (API details)

As an example, we are going to use the consumer API to fetch code information with a scan_id

Scanning Example

Preparation Steps

1. Get some sample QR codes

From the Scantrust Enterprise Portal, download a Scantrust workorder file with QR codes (you can find them in the file codes.csv). In case you already have physical labels, scan one of the QR codes with and QR code reader (for example the Scandit Demo App) and copy the URL. Examples:

  • Production codes: HTTPS://ST4.CH/Q/XK0K93GHYL0418MPP0518YC62732BS1
  • Staging codes: HTTPS://QR1.CH/Q/C0678AB9B80410MRP0410FCF4264BBF

2. Set the landing page to a custom URL

  1. In Scantrust Enterprise Portal, click campaigns on the hamburger menu.

  2. Select the name of the campaign you want to change and click on Option panel

  3. In the Redirect tab, choose Intelligent Redirect for the products in this Campaign

  4. Click Landing Page Powered by Scantrust and select Custom URL

  5. As a Custom URL you will want to fill in the URL where your landing pages are hosted. In order to pass information into the redirect, use a combination of any of the following:

    • qr: extended ID of the code
    • id: unique scan id
    • region: intended market region
    • api_key: only include for testing
    • Example: https://test.com?qr={qr}&scan_id={id}&api_key={api_key}
  6. Copy the Consumer API Key as written below the Custom Url:

KEY

3. Set up Postman and set the Consumer API key

  1. Download and install Postman
  2. In Postman, click the Headers tab just below the address bar
  3. Create a new line and in the KEY column, enter: X-ScanTrust-Consumer-Api-Key

Calling the API to fetch code information

  1. Create a new collection and add a GET request in Postman and set the URL to that of the demo QR Code

  2. Click on Send button to the right of address bar.

  3. The scantrust server will return a 302 REDIRECT response with a Location header. This will contain the redirect for the code. Postman is set to automatically follow this redirect, and it will take you to the landing page as set up for your campaign.

    • Example: https://test.com?scan_id=4fc95ccc-8146-4c0b-b7ce-e232792f182a&qr=C0678AB9B80410MRP0410FCF4264BBF&api_key=eyJjYW1wYWlnbl9pZCI6MTgxfQ:1mfC7C:bvOYaj2tDmxXQpBUyLckJy6repBBkSZPp0EK--aEnW4
  4. From the redirect link copy the scan_id and qr because these will be used to retrieve further information of the code

  5. Create another GET request in Postman and place the endpoint url in the address bar: https://api.scantrust.com/api/v2/consumer/scan/{scan_id}/combined-info/. Replace the {scan_id} with the scan id from step (4).

    • Example: https://api.scantrust.com/api/v2/consumer/scan/9c2722af-6bc1-432e-9a91-d9b0847dfc3a/combined-info/

    postman

  6. Click on Send button and you should receive code information in the response body.

API Response Body

{
"scan": {
"app": "consumer",
"reason": "serial",
"result": "ok",
"auth_failure_mode": "",
"country": "HK",
"age": 14005905,
"created_at": "2021-01-25T07:16:59.304362Z"
},
"code": {
"product": {
"id": 6304,
"name": "st test",
"image": "https://www.scantrust.com/c/1294/brand/bltestfkj.png",
"description": "",
"sku": "st_tester",
"client_url": "http://www.scantrust.com",
"stc_data": {}
},
"brand": {
"id": 954,
"name": "Food & Beverage Brand",
"description": "Food & Beverage Brand, as the name indicates, offers a wide variety of food and beverage products for everyone.",
"image": "https://www.scantrust.com/c/1294/brand/bltestfkj.png"
},
"qrcode": {
"message": "JBF30EODK54710FX56LS7GWC",
"creation_date": "2021-01-24T11:11:13.325035Z",
"serial_number": "KM1207W9",
"is_blacklisted": false,
"activation_status": "active",
"blacklist_reason": "none",
"is_consumed": false,
"is_sid": true
},
"scm_data": [
{
"name": "Consumed Date",
"key": "consumed_date",
"position": 0,
"type": "date",
"value": "",
"value_display": null
},
{
"name": "Sell-by Date",
"key": "sell_by_date",
"position": 0,
"type": "date",
"value": "",
"value_display": null
}
]
"scan_count": 3
},
"campaign": {
"id": 780,
"name": "ST TESTING CAMPAIGN",
"products": [
{
"id": 6304,
"name": "ST Tester",
"image": null,
"brand": {
"id": 954,
"name": "Food & Beverage Brand",
"description": "Food & Beverage Brand, as the name indicates, offers a wide variety of food and beverage products for everyone.",
"image": "https://www.scantrust.com/c/1294/brand/bltestfkj.png",
"client_url": "http://www.scantrust.com"
},
"sku": "unilever_utm_tag_tester"
}
],
}
...