Getting Started

Every Scantrust QR code has a URL and a unique message that identifies it in the system. When someone scans the QR code with a reader, the URL opens and takes them to the correct landing page.

Brand owners can use the Scantrust Landing Page Editor to set up the default landing pages. However, some brands may want to create and host their own pages instead. In that case, developers need to use the Scantrust Consumer API on their landing page to display information about the QR code.

How a QR code is scanned

The user uses the camera app on their smartphone to scan a code.
Their phone displays the URL from the QR code and asks the user to open the link.
After the user opens the link, the scantrust scan-server identifies the code and determines which campaign it is part of.
The scan-server generates a unique scan-id on the server with the scan details.
Using the campaign and the scan-id, the scan-server redirects the user to the landing page and adds the scan_id to the URL.
The landing page uses the scan_id to retrieve information from the scantrust consumer API.
The landing page displays information associated with the scan such as the scan, code, company, campaign, and SCM data.
If the user did not set their location using GPS, the landing page asks the user to share their location and calls the update location endpoint.
If a code is intended for consumption, the landing page can prompt the user to mark the code as consumed.

How to Use the Consumer API

All Scantrust APIs are REST APIs and support JSON. We recommend using a free tool called Postman for testing API calls.

The Scantrust Consumer API offers the following features:

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
- based on scan_id (API details can be found here: /docs/build-with-scantrust/consumer/scantrust-consumer-api)
- based on extended_id (API details can be found here: /docs/build-with-scantrust/consumer/lookup-code-info)
Update the scan location based on user opt-in to share their location (API details can be found here: /docs/build-with-scantrust/consumer/update-location)
Set the code as "consumed" (API details can be found here: /docs/build-with-scantrust/consumer/consume-code)

We will use the consumer API to fetch code information with a scan_id as an example.

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

In Scantrust Enterprise Portal, click campaigns on the hamburger menu.
Select the name of the campaign you want to change and click on Option panel
In the Redirect tab, choose Intelligent Redirect for the products in this Campaign
Click Landing Page Powered by Scantrust and select Custom URL
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}
Copy the Consumer API Key as written below the Custom Url:

KEY

3. Set up Postman and set the Consumer API key

Download and install Postman
In Postman, click the Headers tab just below the address bar
Create a new line of key-value pair. Enter X-ScanTrust-Consumer-Api-Key in the KEY column, and enter your actual API key in the VALUE column

Calling the API to fetch code information

Create a new collection and add a GET request in Postman and set the URL to that of the demo QR Code
Click on Send button to the right of address bar.
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
From the redirect link copy the scan_id and qr because these will be used to retrieve further information of the code
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/
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"
            }
        ],
    }
...

How a QR code is scanned​

How to Use the Consumer API​

Scanning Example​

Preparation Steps​

1. Get some sample QR codes​

2. Set the landing page to a custom URL​

3. Set up Postman and set the Consumer API key​

Calling the API to fetch code information​

API Response Body​