Targets
This section describes the various endpoints to be used for exchanging target variable data between the client’s infrastructure and Trax.
About the target data exchange in general
Trax’ Targets infrastructure can only be used for Trax projects relying on Flex KPIs.
KPIs are organised at Trax’ end into Variable Groups.
-
A Variable Group contains KPIs requiring the same target variable data, eg.
Variable Group: OSA Main Shelf
KPIs added to it: OSA Main Shelf, OSA Main Shelf SKU
Target data: stores, assortment, validity date range . -
The available variable groups can vary from project to project and will be provided by Trax.
Trax’ Targets API allows a bi-directional exchange of targets variable data between the client’s and Trax’ infrastructure by using Excel or CSV files.
This means in particular the following:
-
When adding new or updating existing targets data, these need to be added to an Excel or CSV document which has to be sent in the POST requests (see below).
-
In case an uploaded file fails the validation, the full list of errors is provided by Trax’ response in an Excel file.
-
The target data already added to our database will also be provided by Trax’ response in an Excel file.
The targets data added to the Excel/CSV file should rely on the Trax standard attributes. The basic rules here are:
-
The header row should contain the attribute names in Trax standard format by default - while the subsequent rows should represent the targets data records by having values for the attributes provided in the header.
-
Minimal requirement for the file: it needs to contain at least 1 key, 1 data attribute and a start date.
-
The available attributes/file templates can be provided by Trax.
-
The target data provided in an excel file are to be associated with a variable group containing the KPIs to be applied to.
-
Rules for the target CSV file:
-
Data should be separated by commas.
-
Date formnat: MM/DD/YYYY
-
Example:
store_type,product_ean_code,start_date
SuperMarket,3574661148458,12/01/2022
-
-
Example for an assortment target Excel file:
-
Important limitations:
-
The API is able to process files with max. 400K rows.
-
If contractually agreed on a daily target file update including all targets data, please make sure to send the same date as start and end date.
-
Upload An Excel File With Target Data To Multiple KPIs (Batch)
Get The Data Of An Uploaded File By ID
Available endpoints
Get Errors Of An Uploaded File In Excel
Update A File Upload (Replace The File or Change the Variable Group)
Get The Data Of All Uploaded Files
Download The Target Data In An Excel
Upload An Excel or CSV File With Targets Data
Finalize Upload (commit data to the database)
GET
-
Aim: To enable Clients to retrieve an uploaded targets data file (source file) with all available data (source file, metadata, status etc.) from Trax
-
Use Case: To check the previously uploaded file status to make sure that the uploaded file was valid and - if requested - successfully added to the database.
Response Example - JSON
{
"name": "osamain_new_targets.xlsx",
"variable_group_id": 42,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-11T12:43:48.970000",
"status": "Failed",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",
"updated_time": "2022-08-11T12:43:48.970000",
"id": "62f4f1dd68bcdd097cca1938",
"updated_by": null,
"errors": [
{
"location": "A42",
"value": "HyperMarket",
"error": "Invalid store_type value(s)"
}
{
"location": "B45",
"value": "394398234234",
"error": "Invalid product_ean_code value(s)"
} ],
"variable_group_name": "OSA - Main Shelf"
}
Upload By ID
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (e.g. 'v4')
project_name string *
Project name as provided by Trax
upload_id string *
Unique identifier of the file upload
Supported Protocol: HTTPS
GET /targets/api/:version_number/projects/:project_name/uploads/details/:upload_id
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/my-project/uploads/details/62f4f1dd68bcdd097cca1938
Response Details
The response body will contain the following data:
name string
Name and extension of the uploaded file.
variable_group_id string
Unique identifier of the variable group the file has been associated with.
created_by string
Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user
creation_time date_time
Timestamp of the file upload
status enum
Current status of the file upload, options:
Queued - initial status upon upload
Validation in progress - The uploaded file is being validated
Validated - The uploaded file has passed the validation
Failed - The uploaded file failed the validation
Committed - The uploaded file's data have been committed to the targets database.
file_url string
URL to download the uploaded (source) file. NB: Only authenticated users can download the file!
id string
Unique identifier of the file upload.
issue_id string
Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!
updated_by string
Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user
updated_time string
Timestamp of the file upload update.
errors object
The 1st 10 erroneous rows of the uploaded file, for data structure see below.
variable_group_name string
Name of the variable group the file is associated with.
Error data:
error Object[]
List of the 1st 10 errors found in the uploaded file during validation with the following data:
location string
Cell of the error in the Excel identified with the column-row combination (eg. A2).
value string
Erroneous value found in the cell.
error string
Error description
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Invalid upload id
-
Error Code: 422
-
Error: 1 validation error for Request
path -> template_id
invalid ObjectID specified (type=type_error)
Missing upload id
-
Error Code: 404
-
Error: Template not found
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Incalid authentication token
-
Error Code: 401
-
Error: Invalid authentication token
Request Details
Mandatory fields marked indicated by
*
POST
Supported Protocol: HTTPS
POST /targets/api/:version_number/projects/:project_name/uploads
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads
upload Object[]
List of uploads, each containing the following fields:
name string
Name and extension of the uploaded file.
variable_group_id string
Unique identifier of the variable group the file has been associated with.
issue_id string
Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!
created_by string
Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user
creation_time date_time
Timestamp of the file upload
status enum
Current status of the file upload, options:
Queued - initial status upon upload
Validation in progress - The uploaded file is being validated
Validated - The uploaded file has passed the validation
Failed - The uploaded file failed the validation
Committed - The uploaded file's data have been committed to the targets database.
file_url string
URL to download the uploaded (source) file. NB: Only authenticated users can download the file!
id string
Unique identifier of the file upload.
updated_by string
Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user
errors object
The 1st 10 erroneous rows of the uploaded file, for data structure see below.
Request Details
Mandatory fields marked indicated by
*
{
"name": "upload_OSA_MainShelf.csv",
"variable_group_id": 597,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-09-21T11:50:33.593442",
"status": "Queued",
"file_url": "https://services-int.traxretail.com/trax-one/integ11/files/download/9957bd30-39a3-11ed-bbbc-87636c21d120",
"updated_time": "2022-09-21T11:50:33.593446",
"id": "632afa89e0f7d80e559e0299",
"updated_by": null,
"errors": []
}
Response example - JSON
Response Details
The response body will contain the following data:
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Variable group(s) not added
-
Error Code: 400
-
Error: "variable_group_id must be an integer number"
"variable_group_id should not be empty"
Variable group id not an integer
-
Error Code: 400
-
Error: "variable_group_id must be an integer number"
Missing uploaded file
-
Error Code: 400
-
Error: "Missing uploaded file"
Invalid file extension
-
Error Code: 400
-
Error: "Invalid file extension"
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authentication token
-
Error Code: 403 - Forbidden
-
Error: "Invalid token!'
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Upload An Excel/CSV File With Target Data To One Set of KPIs
-
Aim: To enable Clients to upload a file containing new targets data or targets data updates tied to a certain set of KPIs (Variable Group)
-
Use Cases:
-
To add new targets data/update targets data linked to one Variable Group (certain set of KPIs).
-
To validate a file before uploading it.
-
POST Request File Fields
file *
Excel/CSV file with the targets data
variable_group_id *
Unique identifier of the Variable Group the target data need to be linked to
upload_action enum *
Action to be performed by the API, options:
-
VALIDATE
-
VALIDATE_AND_COMMIT
Mandatory fields marked indicated by
*
-
Rules and options regarding the upload_action:
-
The request body needs to contain one of the following possible actions in the upload_action attribute:
-
VALIDATE_AND_COMMIT
-
VALIDATE
-
-
-
Providing VALIDATE_AND_COMMIT,
-
The uploaded file gets validated and if it contains only valid data, these data will be committed to the targets database.
-
If the file contains (even partially) invalid data, the file’s data (even the valid ones) will not be committed to the database.
-
-
Providing VALIDATE,
-
The uploaded file gets only validated, but not committed to the database. Hence this option can be used for a preliminary file validation. To commit the data to the database, the POST Finalize Upload endpoint needs to be used.
-
Important notes on how to use the endpoint
Error data:
error Object[]
List of the 1st 10 errors found in the uploaded file during validation with the following data:
location string
Cell of the error in the Excel identified with the column-row combination (eg. A2).
value string
Erroneous value found in the cell.
error string
Error description
GET
File Errors
-
Aim: To enable Clients to retrieve the errors found in an uploaded targets data file (source file) during validation
-
Use Case: To check the errors if a file upload failed the validation.
Supported Protocol: HTTPS
GET /targets/api/:version_number/projects/:project_name/uploads/:upload_id/download-errors
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/my-project/uploads/62f4f1dd68bcdd097cca1938/download-errors
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (e.g. 'v4')
project_name string *
Project name as provided by Trax
upload_id string *
Unique identifier of the file upload
Response Details
The response contains the Excel file as a binary string.
Response Example
The file contains all data of the source file, location, error value and error description are added to the rows with errors in an additional column, example:
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Upload id not found
Error Code: 404
-
Error: Upload not found
Invalid upload id
Error Code: 422
-
Error: Invalid upload id
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authentication token
-
Error Code: 401
-
Error: Invalid authentication token
Request Details
Mandatory fields marked indicated by
*
POST
Update File Upload
-
Aim: To enable Clients to replace the uploaded file or change the variable group of a previously uploaded file. NB: updating a file upload is only possible if the file’s data are not yet committed to the database (ie. the file upload status is other than Committed)
-
Use Case: To replace a file having errors with a corrected one.
Supported Protocol: HTTPS
POST /targets/api/:version_number/projects/:project_name/uploads/update/:upload_id
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/update/62f4f1dd68bcdd097cca1938
POST Request File Fields
Mandatory fields marked indicated by
*
file
Excel file with the targets data to replace the original file
variable_group_id string *
Unique identifier of the variable group the file upload should be associated with
Response Details
The response body will contain the following data:
name string
Name and extension of the uploaded file.
variable_group_id string
Unique identifier of the variable group the file has been associated with.
created_by string
Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user
creation_time date_time
Timestamp of the file upload
status enum
Current status of the file upload, options:
Queued - initial status upon upload
Validation in progress - The uploaded file is being validated
Validated - The uploaded file has passed the validation
Failed - The uploaded file failed the validation
Committed - The uploaded file's data have been committed to the targets database.
file_url string
URL to download the uploaded (source) file. NB: Only authenticated users can download the file!
id string
Unique identifier of the file upload.
issue_id string
Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!
updated_by string
Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user
updated_time string
Timestamp of the file upload update.
errors object
The 1st 10 erroneous rows of the uploaded file, for data structure see below.
variable_group_name string
Name of the variable group the file is associated with.
Error data:
error Object[]
List of the 1st 10 errors found in the uploaded file during validation with the following data:
location string
Cell of the error in the Excel identified with the column-row combination (eg. A2).
value string
Erroneous value found in the cell.
error string
Error description
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
No variable group or file
-
Error Code: 400 - Bad Request
-
Error: "Missing data for update!"
Variable group does not exist
-
Error Code: 404 - Not found
-
Error: 'Variable group not found!'
Wrong data format
-
Error Code: 400 - Bad Request
-
Error: "variable_group_id must be an integer number!"
Wrong upload id
-
Error Code: 404 - Not found
-
Error: "Template not found!"
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authentication token
-
Error Code: 403 - Forbidden
-
Error: "Invalid token!'
Response Example - JSON
{
"name": "osamain_new_targets.xlsx",
"variable_group_id": 42,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-11T12:43:48.970000",
"status": "Queued",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",
"updated_time": "2022-08-11T12:43:48.970000",
"id": "62f4f1dd68bcdd097cca1938",
"updated_by": null,
"errors": []
"variable_group_name": "OSA - Main Shelf
}
GET
All File Uploads
-
Aim: To enable Clients to retrieve all uploaded targets data files (source files) with all available data (source file, metadata, status etc.) from Trax
-
Use Case: To get a list of file uploads for reconciliation.
Supported Protocol: HTTPS
GET /targets/api/:version_number/projects/:project_name/uploads?:query_params
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads?limit=100&skip=100
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (e.g. 'v4')
project_name string *
Project name as provided by Trax
limit number
Page size, default: 100
skip number
Offset (starting record), default: 0
Request Details
Mandatory fields marked indicated by
*
Response Details
The response body will contain the following data:
upload Object[]
List of uploads, each containing the following fields:
name string
Name and extension of the uploaded file.
variable_group_id string
Unique identifier of the variable group the file has been associated with.
created_by string
Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user
creation_time date_time
Timestamp of the file upload
status enum
Current status of the file upload, options:
Queued - initial status upon upload
Validation in progress - The uploaded file is being validated
Validated - The uploaded file has passed the validation
Failed - The uploaded file failed the validation
Committed - The uploaded file's data have been committed to the targets database.
file_url string
URL to download the uploaded (source) file. NB: Only authenticated users can download the file!
id string
Unique identifier of the file upload.
issue_id string
Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!
updated_by string
Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user
updated_time string
Timestamp of the file upload update.
errors object
The 1st 10 erroneous rows of the uploaded file, for data structure see below.
variable_group_name string
Name of the variable group the file is associated with.
[
{
"name": "osamain_new_targets.xlsx",
"variable_group_id": 42,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-09T14:43:57.063000",
"status": "Validation in progress",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b2912fd0-17f1-11ed-ad08-590b32c837b3",
"updated_time": "2022-08-11T13:13:28.756000",
"id": "62f272adcc01d0694e29a1d2",
"updated_by": null,
"errors": [],
"variable_group_name": "OSA - Main Shelf"
},
{
"name": "osamain_new_targets.xlsx",
"variable_group_id": 42,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-11T12:43:48.970000",
"status": "Failed",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",
"updated_time": "2022-08-11T12:43:48.970000",
"id": "62f4f1dd68bcdd097cca1938",
"updated_by": null,
"errors": [
{
"location": "A42",
"value": "HyperMarket",
"error": "Invalid store_type value(s)"
}
{
"location": "B45",
"value": "394398234234",
"error": "Invalid product_ean_code value(s)"
}
],
"variable_group_name": "OSA - Main Shelf"
},
{
"name": "osamain_new_targets.xlsx",
"variable_group_id": 42,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-09T14:43:57.063000",
"status": "Committed",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b2912fd0-17f1-11ed-ad08-590b32c837b3",
"updated_time": "2022-08-09T14:47:45.120000",
"id": "62f272adcc01d0694e29a1d2",
"updated_by": null,
"errors": [],
"variable_group_name": "OSA - Main Shelf"
},
]
Response example - JSON
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Missing/wrong query param
-
Error Code: 422
-
Error: 1 validation error for Request
query -> limit
value is not a valid integer (type=type_error.integer)
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authenticatrion token
-
Error Code: 401
-
Error: Invalid authentication token
GET
Download Target Data
-
Aim: To enable Clients to retrieve an excel file with all (active and historical) target data from Trax
-
Use Case: To check the active and historical target data.
Supported Protocol: HTTPS
GET /targets/api/:version_number/projects/:project_name/uploads/download
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/download
Request Details
Mandatory fields marked indicated by
*
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Query Parameters
version_number string *
The current implemented API version. <Major> version (e.g. 'v4')
project_name string *
Project name as provided by Trax
Response Details
The response contains the Excel file as a binary string.
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authentication token
-
Error Code: 401
-
Error: Invalid authentication token
POST
Supported Protocol: HTTPS
POST /targets/api/:version_number/projects/:project_name/uploads/batch
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/batch
Request Details
Mandatory fields marked indicated by
*
{
"OSA MainShelf": {
"name": "batch_upload_OSA_MainShelf.xlsx",
"variable_group_id": 597,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-12T07:02:26.302091",
"status": "Queued",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b8d2b5e0-1a0c-11ed-a6ad-115f921fe0c4",
"updated_time": "2022-08-12T07:02:26.302095",
"id": "62f5fb0268bcdd097cca1950",
"updated_by": null,
"errors": []
},
"SOS": {
"name": "batch_upload_SOS.xlsx",
"variable_group_id": 1722,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-12T07:02:26.565092",
"status": "Queued",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/b8f7ca10-1a0c-11ed-a47b-430fed9059d2",
"updated_time": "2022-08-12T07:02:26.565098",
"id": "62f5fb0268bcdd097cca1951",
"updated_by": null,
"errors": []
}
}
Response example - JSON
Response Details
The response body will contain the following data:
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Variable group(s) not found
-
Error Code: 200
-
Error: "Variable group not found."
Missing/wrong upload action
-
Error Code: 400
-
Error: "upload action schould be VALIDATE or VALIDATE_AND_COMMIT
upload action should not be empty
Missing uploaded file
-
Error Code: 400
-
Error: "Missing uploaded file"
Invalid file extension
-
Error Code: 400
-
Error: "Invalid file extension"
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authentication token
-
Error Code: 403 - Forbidden
-
Error: "Invalid token!'
Request Headers
Authorization string
Value: 'Auth-Token {project auth token}'
Authentication token provided by Trax
Upload An Excel File With Target Data To Multiple KPIs (Batch)
-
Aim: To enable Clients to upload an Excel file containing new targets data or targets data updates tied to a certain sets of KPIs
-
Use Cases:
-
To add new targets data/update targets data linked to one Variable Group (certain set of KPIs).
-
To add new targets data/update targets data linked to different Variable Groups (certain sets of KPIs).
-
To validate a file before uploading it.
-
POST Request File Fields
file *
Excel file with the targets data
upload_action enum *
Action to be performed by the API, options:
-
VALIDATE
-
VALIDATE_AND_COMMIT
Mandatory fields marked indicated by
*
-
Rules and options regarding the uploaded file:
-
This endpoints accepts only Excel files, but no CSVs.
-
It is possible to upload targets data to different variable groups (sets of KPIs), but each variable group should be added to a separate sheet within the excel file.
-
Multi-sheet excel files will be by Trax infrastructure split into single-sheet excels hence the response will also contain an array instead of a single object.
-
-
To connect the targets data provided in the file to a variable group, the variable group’s name should be added as the sheet’s name.
-
Rules and options regarding the upload_action:
-
The request body needs to contain one of the following possible actions in the upload_action attribute:
-
VALIDATE_AND_COMMIT
-
VALIDATE
-
-
-
Providing VALIDATE_AND_COMMIT,
-
The uploaded file gets validated and if it contains only valid data, these data will be committed to the targets database.
-
If the file contains (partially) invalid data, the file’s data (even the valid ones) will not be committed to the database.
-
In case of multi-sheet excels, each single-sheet part will undergo the validation and (in the success case) database commit.
-
-
Providing VALIDATE,
-
The uploaded file gets only validated, but not committed to the database. Hence this option can be used for a preliminary file validation. Please note that currently, there is no possibility to commit a valid file’s data into the database via API - this can only be done manually by Trax.
-
In case of multi-sheet excels, each single-sheet part will undergo validation.
-
Important notes on how to use the endpoint
error Object[]
List of the 1st 10 errors found in the uploaded file during validation with the following data:
location string
Cell of the error in the Excel identified with the column-row combination (eg. A2).
value string
Erroneous value found in the cell.
error string
Error description
upload Object[]
List of uploads, each containing the following fields:
name string
Name and extension of the uploaded file.
variable_group_id string
Unique identifier of the variable group the file has been associated with.
created_by string
Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user
creation_time date_time
Timestamp of the file upload
status enum
Current status of the file upload, options:
Queued - initial status upon upload
Validation in progress - The uploaded file is being validated
Validated - The uploaded file has passed the validation
Failed - The uploaded file failed the validation
Committed - The uploaded file's data have been committed to the targets database.
file_url string
URL to download the uploaded (source) file. NB: Only authenticated users can download the file!
id string
Unique identifier of the file upload.
issue_id string
Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!
updated_by string
Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user
updated_time string
Timestamp of the file upload update.
errors object
The 1st 10 erroneous rows of the uploaded file, for data structure see below.
Error data:
POST
Finalize (Commit) File
-
Aim: To enable Clients to commit the data of a valid file to the Trax Targets Database. NB: works only for uploads which haven't been committed yet to the database (the upload status is not committed).
-
Use Case: To commit the data of a corrected file to the database.
Supported Protocol: HTTPS
POST /targets/api/:version_number/projects/:project_name/uploads/:upload_id/finalize
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/targets/api/v4/projects/myproject/uploads/62f4f1dd68bcdd097cca1938/finalize
POST Request File Fields
Mandatory fields marked indicated by
*
file
Excel file with the targets data to replace the original file
upload_id string *
Unique identifier of uploaded file
Response Details
The response body will contain the following data:
name string
Name and extension of the uploaded file.
variable_group_id string
Unique identifier of the variable group the file has been associated with.
created_by string
Uploader of the file: for manual upload (via Trax UI) the email address of the uploader, for API upload, the constant value api-user
creation_time date_time
Timestamp of the file upload
status enum
Current status of the file upload, options:
Queued - initial status upon upload
Validation in progress - The uploaded file is being validated
Validated - The uploaded file has passed the validation
Failed - The uploaded file failed the validation
Committed - The uploaded file's data have been committed to the targets database.
file_url string
URL to download the uploaded (source) file. NB: Only authenticated users can download the file!
id string
Unique identifier of the file upload.
issue_id string
Jira ticket number used for communication between Client and Trax regarding the file upload. NB: The field is only used for manual uploads (via Trax UI), for API uploads, it remains empty!
updated_by string
Updater: for manual update (via Trax UI), the email address of the updater, for API update, the constant value api-user
updated_time string
Timestamp of the file upload update.
errors object
The 1st 10 erroneous rows of the uploaded file, for data structure see below.
variable_group_name string
Name of the variable group the file is associated with.
Error data:
error Object[]
List of the 1st 10 errors found in the uploaded file during validation with the following data:
location string
Cell of the error in the Excel identified with the column-row combination (eg. A2).
value string
Erroneous value found in the cell.
error string
Error description
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Invalid upload ID
-
Error Code: 422
-
Error: 1 validation error for Request
path -> template_id
invalid ObjectID specified (type=type_error).
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Invalid authentication token
-
Error Code: 403
-
Error: Invalid token.
Response Example - JSON
{
"name": "osamain_new_targets.csv",
"variable_group_id": 42,
"issue_id": null,
"created_by": "api-user",
"creation_time": "2022-08-11T12:43:48.970000",
"status": "Committed",
"file_url": "https://services.traxretail.com/trax-one/myproject/files/download/af288a40-196e-11ed-a47b-430fed9059d2",
"updated_time": "2022-08-11T12:43:48.970000",
"id": "62f4f1dd68bcdd097cca1938",
"updated_by": null,
"errors": []
"variable_group_name": "OSA - Main Shelf
}