Skip to main content

Download Code Data

UAT token permissions​

The UAT token needs to have access to the following permissions:

  • codes_view

The UAT token must be set in the header fields of all requests as described in Authentication & Tokens.

Code Data Search Filters​

To download your Code Data, you need to:

  1. Find the campaign ID of the products on which your codes are applied.
  2. Optional: if you want to filter on products or SCM fields, you meed to find the scm field keys and product id's
  3. Filter the codes: use the campaign ID, time-range, product or SCM fields as filters to find your codes
  4. Generate a search task
  5. Check the status of this search task until the status is complete
  6. Generate a download link
  7. Download the codes in CSV format

1. Find your campaign ID​

  1. Log on to the portal and click on CAMPAIGNS in the left hamburger menu
  2. On the campaign for which you want to download the data, click the DASHBOARD icon
  3. When the dashboard opens, the URL in the browser will show https://portal.scantrust.com/#/dashboard?tabIndex=0&campaignId=126&page=1
  4. The campaign-id needed is in the value of the parameter campaignId=

2. Find your campaign SCM Field Keys (optional)​

  1. Log on to the portal and click on CAMPAIGNS in the left hamburger menu
  2. On the campaign for which you want to download the data, click the OPTIONS icon
  3. Click the SCM T&T tab
  4. From the right pabel, copy the keys of each of the active fields (in brackets behind the label).
  5. Use these keys to filter the code-search if required

3. Filter the codes​

All of the filters used in the portal in the codes created screen can also be user to filter the code downloadsd. Some of the options are:

  • time-range (timeframe or date_from / date_to)
  • flags (counterfeit / genuine etc.)
  • code activation status (inactive / active / blacklisted)
  • SCM fields (as defined for the campaign, for example intended_market, case_no etc.)

4. Create a search task​

GET: /api/v2/codes/download/?campaign=2084​

ParameterRequired?Description
campaign_idrequiredID of the campaign
timeframeoptional-1y (year), -1m (month), -1w (week)
or
date_fromoptionalISO date (ie. 2018-12-21T23:59:59.549Z)
date_tooptionalISO date (ie. 2018-12-21T23:59:59.549Z)
activation_statusoptionalinactive=0, active=1, blacklisted=2
{scm field}optionalAny SCM field key/value as a filter.
productoptionalproduct ID (not SKU)

Examples

Show all scans for campaign 195 which are blacklisted and which have intended_market set to "China" (Zh):

/api/v2/dashboard/scans/?campaign=195&flags=out-of-market&limit=2000&offset=0&scm_intended_market=zh&timeframe=-1m

Show all scans for campaign 195 made between 2021-01-31 and 2021-05-18 for product 332:

/api/v2/dashboard/summary/?campaign=195&date_from=2021-01-31T16:00:00.000Z&date_to=2021-05-18T15:59:59.000Z&flags=&product=332

Show all scans for campaign 195 made in the past year which were for codes which are inactive (activation_status=0):

/v2/dashboard/summary/?activation_status=0&campaign=543&timeframe=-1y

Response (200): Status OK

Because the data generated by this search can range in the millions, this endpoint first generates a task which will run in the background. It will then generate a document_key

{
  "document": {
    "key": "mfoi66hz93c9"
  },
  "task": "rq:job:e6f16079-f368-4d8f-940a-7c0266e03d02"
}

The client needs to extract the document_key from the response and use it in the next request to check the generation-status:

5. Check the status of your search task​

GET: /api/v2/documents/{document_key}​

parameter: document_key as retrieved from the previous request

Response (200): Status OK

{
  "key": "mfoi66hz93c9",
  "description": "",
  "status": "complete",
  "category": "code",
  "doctype": "search-result",
  "related_id": null,
  "parameters": {
    "campaign": "2084",
    "activated_at": "2019-09-30T16:00:00.000Z,2021-01-31T16:00:00.000Z"
  },
  "file_size": 253,
  "row_count": 0,
  "expires_at": "2021-04-17T02:31:59.467855Z",
  "is_expired": false,
  "created_at": "2021-04-15T02:31:58.385106Z",
  "company": 446,
  "owner": 391,
  "created_by": 391
}

The response will contain the key, status as well as the parameters used to do the search. Once the status has reached complete, another request can be made to create a download link. The field row_count will indicate how many codes were found.

parameter: document_key as retrieved from the previous request

Response (200): Status OK

The response will contain a secured download link to the search result CSV file:

{
  "link": "https://api.staging.scantrust.io/api/v2/documents/download/yNKtdRwgAdLYUTKMLSOYkJHDGgSBLxUS/"
}

7. Download the CSV file​

When that link is downloaded, the server will send a response as a 302 - redirect The response sends the client to the CSV file in the Scantrust Amazon S3 bucket

Note: After following the link, the download link becomes invalid. Please ensure the download happens as soon as possible after generating the link

Note:

  • the CSV file is compressed in zip-format and needs to be unpacked
  • the CSV file is formatted as comma-separated double-quoted with header.

Response (200): Status OK

Example CSV:

"extended_id","serial_number","brand","product","sku","status","blacklist_reason","scm_updated_by","scm_updated_at","activated_by","activated_at","workorder_id","farm_name","organic","harvest_date","sent_to_plant","plant","sell_by_date","temp_humid_in_ph","shipped_from_plant","arrived_in_dc","dc_name","temp_humid_in_dc","shipped_from_dc","case_number"
"D7BDCA03B80610826432DAD3","","American Pork","Pork","259052703982","active","none","","","","","3413","","","","","","","","","","","","",""
"DE8429F00C043SMPHGG3SCE54D3DBE2","","American Pork","Pork","259052703982","active","none","","2019-06-14T09:35:08.207234+00:00","jelle@test.com","2020-02-13T08:43:54.256017+00:00","3414","","","","","","","","","","","","",""
"F628FC48BC043SMPHGG3S4E54681B26","","Queen Victoria","Lettuce","060556200408","active","none","j@test.com","2018-06-14T20:03:33.627564+00:00","","","3414","Aliso Farms","No","2018-06-14","2018-06-14","Packaging Plant 1","2018-06-14","36°F 95%","2018-06-15","2018-06-15","UST","36° 95%","2018-06-16","52C3F83EAA043SMPHGG3S9E4483193F"
"70E19832F1043SMPHGG3S64644B7B66","","American Pork","Pork","259052703982","active","none","j@test.com","2018-06-13T23:21:40.214562+00:00","","","3414","Aliso Ranch","No","2018-06-14","2018-06-14","Processing Plant 1","2018-06-21","36°F 85%","2018-06-15","2018-06-15","UST","36°F 85%","2018-06-15","FD27177428043SMPHGG3S2824AA697A"
"4324CAC06E043SMPHGG3SF124F8BADE","","Queen Victoria","Lettuce","060556200408","active","none","scmuser@test.com","2018-05-26T17:14:12.055232+00:00","","","3414","ST Test","","","","","","","","","","","",""

For a glossary of all the code fields see Code Data Glossary