How to Upload SCM Data Via Scantrust API

To upload SCM data to the Scantrust API, Scantrust supports two methods, Synchronous and Asynchronous, each with its limitations and benefits. Before choosing which method is most suitable for your use case, make sure you understand the differences.

Synchronous SCM Uploads​

When uploading data synchronously, the API will process and update all your data within the duration of the HTTP call. If a lot of data is sent, or a lot of codes are updated, this method can potentially time out, requiring resending the request. For this reason, the synchronous update method is only useful for low data volumes

Asynchronous SCM Uploads​

When uploading data asynchronously, the API will create a background job to update your data and responds immediately with atask_id, thistask_id response can be used to check the job status (pending, running, error, ...)

Choosing between Synchronous and Asynchronous

​Synchronous updates are the easiest to set up due to the immediate response.  It is however only recommended in cases where the number of updated codes is low (fewer than 1000), whereas, when the Asynchronous method is required for SCM updates, your integration will have to check back on thetask_idto find out the result of the SCM update.

Important

To upload data whether, by Synchronous or Asynchronous method, you will need a UAT token with the following permissions: 

• codes_view
• scm_bulk_edit
• scm_code_edit
• product_view

Additionally, it is important to be sure that:

• Brand owner/SCM User account on the Scantrust portal:
• A campaign that is set up to include the desired SCM fields:
  • Example: production_date, intended_market, RFID,...
  • Note: SCM fields not included in the campaign will be discarded by the system.
• A work order for a product that is included in the campaign, and which has valid codes to be updated.

To get access to the Scantrust REST API, you can use an API platform such as Postman, this is the world's most popular API platform, with over 17 million users and 500,000 organizations worldwide. The tool comes with a flexible, and collaborative environment that allows you to design, develop, document, and test your APIs faster.

You can try the web application or download and install this app from this link: https://www.postman.com/downloads/. In any case, you must sign up with a valid email address.

Note: In the Scantrust context, Postman should be used only for testing purposes. It should not be intended to use on real scenarios or project implementations. 

Steps to configure Postman:

1. Please open Postman, in the home page you should be able to see the following:

2. Then, please on the tap labeled: “Workspaces”, in the upper left corner: 

3. Then, please click on the option labeled: “My workspace”: 

4. Once you are in your workspace, please click on the “+” sign as follows: 

5. After that, a new tab will appear with a preconfigured API request: GET:

6. Now, it is important to set up the API Authorization, to do that, please click on the tab labeled as:               “Authorization”: 

7. Then, click on the "Type" section and select: "API Key" option, as follows: 

8. Now, type the word: "Authorization" on the key field, then copy your UAT token from the ST portal            and paste it into the field labeled as: “Value”, including the characters UAT: UAT [your token],                    leaving a spacebar between the UAT string and the token: 

9. Then, go to the “Body” tab, select “raw” and select “JSON”:

Steps to Upload SCM - Synchronous

Data must be uploaded using JSON as the format. The API will accept batches of items not larger than 100 per call. Therefore the data must be split into batches of max 100 items per POST request. It is recommended to keep a log file containing the keys/batch # of previously uploaded items so they can be skipped when uploading. This prevents items from getting uploaded twice if the API intercepts a defective item in a specific batch.

1. To set up this POST request you must type the URL, which in this case is the following: https://api.scantrust.com/api/v2/scm/upload: 

2. Then, on the body tab, you have to set the JSON, following an example: 

{
"data_key": "extended_id",
"items": 
[
  {"extended_id": "HGDTQD54D5SD86EEDFS", "intended_market": "cn"},
  { "extended_id": "JF5FPO58DFITE4EDXD2", "intended_market": "de"}
]
}

In which, the "data_key" must be chosen to select the desired codes to upload data for. There are 2 ways to determine a key:

• By default, this key will be extended_id (the unique message each code holds).

• The key can also be set to serial_number if they are set on the codes.

Moreover, the "items" refers to the list of SCM data in key/value pairs, to upload to individual codes. Each data key needs to reference the key of the SCM field as defined in the campaign. The names of the keys can be confirmed by downloading the template.csv file from the SCM T&T tab for the campaign.

3. Once you finish your code script, we can click on the SEND button:

4. When a batch of max 100 codes is successfully posted, a response with affected and posted codes will be given. Following the response you should get:  

5. Last but not least, you can check if those codes were affected by this update, on the "Codes Transactions", a section in the Scantrust portal:

In this case, for a specific code, we updated the intended_market field to china. 

Steps to Upload SCM - Asynchronous

Similarly to the Synchronous process, It is important to be sure that:

• Brand owner/SCM User account on the Scantrust portal:
• A campaign that is set up to include the desired SCM fields:
  • Example: production_date, intended_market, RFID,...
  • Note: SCM fields not included in the campaign will be discarded by the system.
• A work order for a product that is included in the campaign, and which has valid codes to be updated.

Data must be uploaded using JSON as the format. The API will accept a maximum of 5 constraints, with a maximum of 1K values. Data must be split into batches of items that contain the same SCM data. It is recommended to keep a log file containing the keys/batch # of previously uploaded items so they can be skipped when uploading. This prevents items from getting uploaded twice if the API intercepts a defective item in a specific batch.

1. To set up this POST request you must type the URL, which in this case is the following:  https://api.scantrust.com/api/v2/scm/upload/async/: 

Posting data to this endpoint will create an ASYNC server job that can edit any code in your company to contain the desired SCM data. The endpoint will return a task_id which can be used to check the status of the job.

2. Then, on the body tab, you have to set the JSON, as follows:

{
 "constraints":{
        "extended_id": ["ACsofByKKTvj", "Bjr1U5dt3M8X", "JKZlcPU6Za4q"]
  },
 "scm_data": {
        "purchase_number": "test19102022"
  },
 "reference": "SCM Upload"
}