Product Upload

Overview

This document covers the process of uploading a product to the Scantrust API.

Components

Upload handler that formats, pre validates and uploads the data
Endpoint on the server that accepts a batch of records

Prerequisites

There are 2 main prerequisites to fulfill:

Brand owner on the Scantrust portal:
- Scantrust will provide a developer test-account as well as a production account.
At least one Brand set up in the Portal:
- The brand ID can be retrieved from the /api/v2/brands/ endpoint.

Upload Handler

Overview

The upload handler will communicate with the API endpoint, handle the data to be uploaded and processes the response from the server.

Workflow:

Obtain a UAT token
Pre-validate data to be uploaded
Format data to be uploaded to the specified JSON structure
Upload JSON data to the API
Process the response

Obtain a UAT token

In order to call these API endpoints, an User Authentication Token (UAT) must be included in the POST header.

See the section authentication and tokens

Pre-Validation of uploaded file

It is recommended to pre-validate the data to be uploaded. This prevents unnecessary calls to the API.

Following pre-validation should be done:

Format Checking:
- Verify the data contains all required fields.
- Verify that all items have the same # of fields.
Preliminary Error Checking:
- Verify that no ‘SKU’ value is duplicated.
- Verify that no ’SKU’ value is blank.

Format data to be uploaded

Data must be uploaded using JSON as the format. The API will accept only one product per call. Therefore the data must be split into batches of max 1 item per POST. It is recommended to keep a log file containing the SKU of previously uploaded products so they can be skipped when uploading again.

General flow:

Process the data and create an array of JSON objects.
Create batches 1 object each.
Ignore previously uploaded rows.
Convert all values to strings.
Send request.
Send a request and save the SKU as 'uploaded' in a logfile:
- Subsequent runs should ignore all keys that are in the 'uploaded' file.

See API design: /api/v2/products/

Upload the data

A POST request containing the formatted data of max 1 item is made to the /api/v2/products/ endpoint. This POST request should contain the UAT obtained from the API.

The AUT is sent in the request header as follows:

headers={"Authorization": "UAT " + token}

API design: /api/v2/products/

API Design

POST: /api/v2/products/

Uploads a product for any brand the company owns. One item per POST is allowed. Multiple requests can be made to update more items.

Attribute	Required?	Description
sku	required	Unique product SKU in the company.
brand_id	required	Foreign Key to a brand owned in the company. This value must be passed as an ID. A brand ID can be retrieved by doing a GET call to the /api/v2/brands/ endpoint.
name	required	Name of the product.
description	optional	A brief description of the product.
client_url	optional	A product URL that may be used to redirect codes if a campaign is not active for the product.
image	optional	Include a product image, typically used on STC landing pages. If not set, the brand image will be used. To upload images use multipart.
campaign	optional	The ID of an existing campaign in the company to which this product must be added.

Body Parameters POST (application/json)

{
    "sku": "PR1", 
"brand_id": "50", 
"name": "Product One", 
"description": "The first product in a line of many others.", 
"client_url": "http://www.examplebrand.com/productone", 
}

Response (200): Status OK

When a product is successfully posted, a response will be given.

{  
   'sku':u'PR1',
   'client_url':   u'http://www.examplebrand.com/productone',
   'description':u'The first product in a line of many others.',
   'campaign':None,
   'image':None,
   'brand':{  
      'image': '',
      'id':50,
      'name':u'\u563b\u563b\u8e22\u5371'
   },
   'uuid':u'544d8576-e7e1-4312-8fba-7ef31f5d1333',
   'label':u'Product One',
   'brand_id':512,
   'is_archived':False,
   'creation_date':   u'2017-02-21T10:25:34.142651   Z',
   'company':{  
      'id':744,
      'name':u'test brand owner 2',
      'uuid':u'd47b8be2-c8e3-4f78-a55d-563f678f0c5c'
   },
   'id':1081,
   'name':u'Product One'
}

Response (400) : Invalid Data Format

An exception will be raised when any of the following is detected in a product:

Duplicate SKU
Invalid brand ID
Required fields left empty

error Json example 400:

{
    "brand_id": [
        "Invalid pk \"686\" - object does not exist."
    ]
}

PATCH: /api/v2/products/{id}/

Endpoint to patch (update) existing products. Any number of editable fields can be patched and adjusted for this specific product. Updating requires the ID of the product to be appended to the endpoint URL. When patching, all fields are optional and only the posted fields will be adjusted.

Attribute	Required?	Description
sku	optional	Unique product SKU in the company.
brand_id	optional	Foreign Key to a brand owned in the company. This value must be passed as an ID. A brand ID can be retrieved by doing a GET call to the /api/v2/brands/ endpoint.
name	optional	Name of the product.
description	optional	A brief description of the product.
client_url	optional	A product URL that may be used to redirect codes if a campaign is not active for the product.
image	optional	Include a product image, typically used on STC landing pages. If not set, the brand image will be used. To upload images use multipart.
campaign	optional	The ID of an existing campaign in the company to which this product must be added.

Body Parameters POST (application/json)

PATCH /api/v2/products/50/
{
"description": "The first product in a line of many others.", 
"client_url": "http://www.examplebrand.com/productone", 
}

This updates only the description and client_url of product with ID=50.

Upload images

To upload images Multipart needs to be used. See the python example below:

product_id = 1
def patch_multipart(self, path, files, data, raw_resp=False):
    resp = requests.patch(
        url=self.server_url + path,
        data=data,
        files=files,
        headers=self._auth()
    )
    if raw_resp:
        return resp
    self.validate_resp(resp)
    return resp.json()
with open('image.jpeg', 'rb') as f:
  files = {'image': ('image.jpeg', f)}
  resp = self.server.patch_multipart('/api/v2/products/%s/' % product_id, data=None, files=files)

GET: /api/v2/products/?sku__exact={sku}

This endpoint can be used to retrieve a specific product ID by SKU. By passing ?sku__exact in the endpoint URL, the system will look for an exact match within the company's products. Only one result should be returned since SKU is unique per company.

Response (200): Status OK

When a product is successfully found, a response will be given. The results comes as a LIST. The first object in that list should be taken to know the ID.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 959,
            "uuid": "701b1a6f-e751-4c20-8012-028063322fb0",
            "sku": "prod2",
            "image": null,
            "name": "Product #2",
            "description": "",
            "label": "Product #2",
            "brand": {
                "id": 749,
                "name": "100 Brand",
                "image": null
            },
            "company": {
                "id": 871,
                "uuid": "1fc1a571-1918-4f7d-b826-510752156cdf",
                "name": "Test brand"
            },
            "brand_id": 749,
            "creation_date": "2017-02-16T08:59:08.774705Z",
            "client_url": "",
            "is_archived": false,
            "code_count": 0,
            "active_code_count": 0,
            "blacklisted_code_count": 0,
            "campaign": {
                "id": 188,
                "name": "test campaign",
                "description": "camp",
                "is_archived": false
            }
        }
    ]
}

Example product not found:

{
    "count": 0,
    "next": null,
    "previous": null,
    "results": []
}

developer portal

Android

iOS

API Docs

Samples

Overview

Components

Prerequisites

Upload Handler

Overview

Workflow:

Obtain a UAT token

Pre-Validation of uploaded file

Format data to be uploaded

General flow:

Upload the data

API Design

POST: /api/v2/products/

Body Parameters POST (application/json)

Response (200): Status OK

Response (400) : Invalid Data Format

PATCH: /api/v2/products/{id}/

Body Parameters POST (application/json)

Upload images

GET: /api/v2/products/?sku__exact={sku}

Response (200): Status OK

Example product not found: