Routes
API endpoint to get information about Store entities along with info on how to format Store POST request via async-job
Retrieve Routes Data
Creating, Deleted, and Updating Routes
POST
Creating, Deleting, and Updating routes in Trax is done asynchronously. The routes POST should be done via the async jobs framework using the information below
Route Update Operation Details
Operations are done in an "update + insert" style:
-
In order to add a new route:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
-
In order to update a route:
-
Add an object/row with all the required fields. The operation will succeed only if all the mandatory fields will be provided
-
The unique identifier of a store is the 'external_route_id' field. This field is not editable
-
Empty field values will be treated as setting a field value to null
-
Request Example
Assume that Trax already contains valid data for 3 routes, with identifiers 1,2, and 3 (according to their external_route_id value), and without any data other than the mandatory fields.
In the JSON and CSV examples below, the following effect will occur on the data that is stores in Trax:
-
Route 1 will be added. Note that all mandatory fields are listed. The stores with identifiers 100, 200, 300 will be assigned to the route. The users with identifiers 10,20,30 will be assigned to the route
-
Route 2 will be updated, and its "description" field will be set to "description of route"
-
Route 3 will be updated, the store's connection to the route will be removed, and the route cycles will be deleted
Route POST Request File Fields
Mandatory fields marked indicated by
*
name string (128) *
Name of the route
description string (256)
A short description of the route
external_route_id string (128) *
The client's route unique identifier
is_deleted boolean
If the boolean is true: the route will be deleted
If the boolean is false: the delete flag will be removed.
N.B. false is the default state, if this key does not appear and the route was deleted, then the route will be active again.
entities Object[]
An array of entities that are linked to this route. The entity fields are:
stores Array
List of store numbers, Maximum 500 stores per
route
users Array
List of users login names
cycles Array
List of cycle objects linked to the route, each containing the following fields:
description string
Descriptor of the cycle
start_date Date
day/month/year
end_date Date
day/month/year
Request Example - CSV
name,external_route_id,description,entities.stores,entities.users,is_deleted,entities.cycles
route_1,1,,"100,200,300","john.doe@myemail.com,jane.doe@myemail.com,paul.smith@myemail.com",FALSE,"{"description": "November 2020","start_date": "01/11/2020","end_date": "30/11/2020"}"
route_2,2,description of route,,,FALSE,
route_3,3,,,,FALSE,
[
{
"name" : "route_1",
"external_route_id" : "1",
"entities":{
"stores" : ["100","200","300"],
"users" : ["john.doe@myemail.com",
"cycles": [
{
"description": "November 2020",
"start_date": "01/11/2020",
"end_date": "30/11/2020"
}
]
}
},
{
"name" : "route_2",
"description" : "description of route",
"external_route_id" : "2"
},
{
"name" : "route_3",
"external_route_id" : "3",
"entities":{
"stores":[],
"cycles": []
}
}
]
Request Example - JSON
GET
Supported Protocol: HTTPS
GET /api/:version_number/:project_name/entity/routes?:pagination_params
curl -K -H "Authorization: Auth-Token YOUR_PROJECT-API-KEY" https://services.traxretail.com/api/v4/my-project/entity/routes?sort=namer&page=1&per_page=10
metadata object
Info related to pagination
routes Object[]
List of route objects. Each containing the following fields:
name string
Name of the route
description string
A short description
external_route_id string
The client's Route unique identifier
is_deleted boolean
True/False
entities Object
An Object of entities that is linked to the route. It contains the following fields:
stores Array
List of store numbers, Maximum 500 stores per route
users Array
List of users' login names
cycles Array
List of cycle objects linked to the route, each containing the following fields:
description string
Descriptor of the cycle
start_date Date
day/month/year
end_date Date
day/month/year
Request Details
Mandatory fields marked indicated by
*
{
"metadata": {
"page": 2,
"per_page": "10",
"page_count": 1167,
"total_count": 11668,
"links": {
"self": "/api/v4/my-project/entity/routes?sort=namer&page=1&per_page=10",
"first": "/api/v4/my-project/entity/routes?sort=name&page=0per_page=10",
"previous": "/api/v4/my-project/entity/routes?sort=name&page=0&per_page=10",
"next": "/api/v4/my-project/entity/routes?sort=name&page=2&per_page=10",
"last": "/api/v4/my-project/entity/routes?sort=name&page=1166&per_page=10"
}
},
"routes": [
{
"name": "Eastern Russia",
"description": "Eastern Russia route",
"external_route_id": "222",
"entities": {
"stores": ["100", "200", "300"],
"users" : ["john.doe@myemail.com",
"cycles": [
{ "description": "November 2020",
"start_date": "01/11/2020",
"end_date": "30/11/2020"
}]
}
},
{
"name": "route_1",
"external_route_id": "333",
"is_deleted": false
}
],
}
}
Response
Response Details
The Routes GET reply body will contain the following fields:
Validation and Errors
The following are the validations and errors that may appear due to an invalid GET request:
Unknown Field
-
Error Code: 400 - Bad Request
-
Error: Unknown Field: <field_name>
Internal Server Error
-
Error Code: 500 - Internal Server Error
-
Error: Trax Internal Error
Incorrect or expired token
-
Error Code: 401 - Unauthorized
-
Error: Incorrect or expired token
Requesting a forbidden resource
-
Error Code: 403 - Forbidden
-
Error: A forbidden resource has been requested <resource>
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
pagination params
For more info see the pagination page. By default the first page will be returned first
Response, Validation, and Errors
The initial response for a valid async job request will be 202 Accepted.
When the async job is queried, the outcome of the job will be available only when the status is 'done'.
For more info, see the Async-Jobs page
Validation and Error File
When uploading the file, the Trax system runs numerous validations on the file to confirm it has all the necessary fields.
Should there be issues with the file, an error file will be generated. This file is provided in both JSON and XLS format. Each entry with an error will contain the name of the route, and the external_route_id It will also contain one or several of the following errors based on failing the related validation:
Error Object File Fields
name string
Name of route
external_route_id string
The client's route unique identifier
errors Array (string)
Errors associated with the route, see below for list
Error types
Mandatory Variables - Missing Mandatory
Fields During creation
-
external_route_id is required
-
external _route_id is a mandatory field and should be provided
-
-
name is required
-
name is a mandatory field and should be provided
-
Incorrect Format - Email Format will be validated
-
name is not allowed to be empty
-
name is a mandatory field that cannot be empty
-
N.B. Please note that requests with unrecognizeable names or invalid values for non-mandatory fields will still be accepted and apart from such fields, all requested changes (creation, update or deletion) will be processed
[
{
"name": "Eastern Russia",
"external_route_id": "100",
"errors": [
"Unknown store_number:10"
]
}
]