Upload your own codes <DEPRECATED>

Overview

This document is deprecated and will be removed soon. PLease migrate to one of the new code upload methods as described in the ingestion overview.

Scantrust has been designed to efficiently manage a large volume of codes. As such, new codes are created asynchronously in the background through a workorder mechanism to ensure the system can support these quantities. The newly created codes can thereafter be downloaded in a zip archive, which are in the Scantrust Compact-12 format.

The Code Upload API allows brand owners to upload files containing their unique identifiers in any format, as long as they meet the length and allowed characters requirements outlined by the Scantrust system (see below). When using the Code Upload API, users can assign different products to each code and choose the SCM fields that apply.

The code upload API can generate 2 types of codes:

1. Serialized Identifiers (SID) codes: these codes are scantrust QR codes without the secure graphic. The brand owner can self-generate and download these codes and they do not require a printing partner.
2. Secure Codes (SSC): these codes contain the copy-protection secure graphic and require a printing partner with calbrated equipment and substrate. These codes are generated and assigned to an existing workorder with a secure graphic, which is then printed by a printing partner

UAT token permissions

To access this API, a UAT token needs to be provided which has access to the following permissions:

• workorder_view
• workorder_download
• workorder_sid_download
• ingestion_view
• ingestion_cancel
• ingestion_code_create
• product_view

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

Uploading Serialized Identifiers (SID) Codes

Example CSV file with a header

id,product,pallet_number,intended_market
abc12345,sku1,pal1,BE
def12345,sku1,pal1,NL
ghi12345,sku1,pal2,DE
jkl12345,sku1,pal2,FR
...

• required: a column with header id containing the unique identifiers
  • each id must be 8 characters or longer
  • each id can only contain valid characters (a-z, A-Z, 0-9, -, _). For example: aB1_3dZ97-x2 or 123abcd89XYZ
  • regex for the id: ^[A-Za-z0-9_-]{8,}$
• optional columns:
  • product containing a product-sku which already exists in the scantrust system
  • activation_status containing 0 (inactive), 1 (active) or 2 (blacklisted)
  • additional columns containing scm fields with the header as the scm key (ie. pallet_number etc.)

Steps to upload your codes

1. Use the create Ingestion endpoint and retrieve an ingestion key with S3 file upload details
2. Using the file upload details, upload the file to the S3 endpoint
3. Call the process the ingestion file endpoint to start the code validation and processing. This will generate a workorder and start the code creation task
4. To get the details of a submitted Upload and to check if there were no errors, call the ingestion record endpoint
5. Finally, once the workorder is done processing, call the download workorder serial numbers endpoint to download the workorder file with the example image and csv format. See the (Downloading Workorders section)) for more information on the file content(s).

API Design

Create Ingestion Record

POST /api/v2/ingestion/codes/upload/get-post-data/

Generate an ingestion record

Attribute	Required	Description
filetype	required	json or csv

Example JSON Payload

{
   "filetype": "csv"
}

Response (201): Created

{
   "post_data": {
       "url": "https://st-media-dev.s3.amazonaws.com/",
       "fields": {
           "Content-Type": "text/csv",
           ...
       }
   },
   "record_key": "p37bk370jurt"
}

This response is used to make a call to the S3 endpoint as in the URL. All the fields retrieved must be posted to this URL and are frequently changed. Please POST them dynamically from the fields dict retrieved here.

Validations and errors

Response (400): invalid file type is posted

Upload the File to S3

POST {S3 URL}

This call uses the URL retrieved in the previous call (Ingestion File Upload API) to upload your file S3 for processing by Scantrust. The fields retrieved in the fields dictionary must all be dynamically posted to the S3 URL. The content and amount of fields might change overtime.

Field	Value	Description
< fields >	fields	All fields dynamically retrieved by the get-post-data endpoint

Response (201): Created

Process Ingestion File

POST /api/v2/ingestion/codes/upload/process/

Starts the ingestion process from a file previously uploaded to the S3 storage by calling the post-data endpoint. The process is started asynchronously.

Fields	Value	Description
default_scm_data	json	SCM data field including product/activation_status/blacklist_reason/… WOrks the same as the SCM upload endpoints. Data here will be used as the default for each code (overridden by what is in the code record)
url_prefix	String (Optional)	URL prefix to be used on the work order
allow_posted_duplicates	Bool (Optional)	Don’t error on duplicate check but ingest first entry and ignore next duplicates (within posted IDs)
record	String	Record Key

Example

{
    "record": "xvg24feojYz", 
    "default_scm_data": { 
        "activation_status": 1,
        "product": "NICK1",
        "updated_by": "warehouse_1"
    }, 
    "allow_posted_duplicates" : true
}

Error responses

HTTP Code	Message	Reason
400	Only code ingestion records of type S3 in state 'uploading' can be processed.	Triggered when posting a record which is in the wrong state
400	Invalid record	Triggered when a non-existing record is posted
400	Uploaded file not found.	Triggered when a previously uploaded file is not found

Ingestion Record

GET /api/v2/ingestion/{key}/

Gets a list of IngestionRecords

Response 200

{
   "count": 18,
   "next": null,
   "previous": null,
   "results": [
       {
           "id": 22,
           "key": "ym0mse71lc7t",
           "description": "Code ingestion file upload",
           "status": "error",
           "type": "code",
           "ingestion_mode": "api",
           "created_at": "2022-10-19T17:17:11.750258Z",
           "created_by": 1,
           "status_updated_at": "2022-10-26T13:51:15.701033Z",
           "parameters": {
               "default_scm_data": {},
               "use_serial_number": false
           },
           "result_data": {
               "errors": [
                   {
                       "duplicate_id_error": [
                           "iE4Mw…",
                           "Bc2m6…"
                       ]
                   }
               ]
           }
       },
       ...
    ]
}

Filters

Usage example:

/api/v2/ingestion/?type=code

Supported filter fields:

• type
• status
• ingestion_mode