Data API Login

The Application Programming Interface (API) allows third party software external to the TOTECS platform to have the ability manage data within a TOTECS project, and each of its hosted websites. Using the API allows other third party software developers to develop sotware tools that can automate the data that is imported into a TOTECS project, and/or exported.

The Data API runs as a RESTful web service. This allows HTTP connections to be used to connect to the API and transfer data using the GET, and POST HTTP methods. In the sections below are listed the end points that the describe how software can interact with an aspect of the API. Each endpoint typically returns a reponse in the JavaScript Object Notation (JSON) data format.

Security

In order to use the API a session first needs to be created by using a user's credentials to login. To import data through the API this user must be an administrator assigned to Admin Permissions Role that has the "Modify Data with Data Import and API" set to allow. This ensures that the software using the API has the permissions to modify data within a given TOTECS project. To export data from the API the credentials of a normal user must be given, with the user assigned to a Facility Permissions Role that allows exporting permissions turned on for the relevant data export. 

Once a session has been obtained then the session ID needs to be placed into the URL when using all other endpoints to import, or export data.

Sessions will timeout after a period of time, and its highly advisable to any 3rd parties using the API to destroy their sessions once they have finished using the Data API.

All requests to use the Data API are only allowed using the HTTPS protocol, this ensures that any data transferred is encrypted over the internet, and securely transferred.

The endpoint creates a new user session in the API by logging into a project with the credentials of an existing user. This endpoint must be called first in order to obtain the session ID that is required for other endpoints. Ensure that the credentials of the user given are either an administrator user who is assigned to the Admin Role permission havine the "Modify Data with Data Import and API" permission set to allow, or the user is a normal user and the "Allow Users To User Data API" setting is turned on. It is recommended that a separate administrator or normal user is created within a project that is dedicated solely to using the API. This can reduce the chances of the user's settings being modified, or 3rd party systems being blocked from accessing the API if a person decided to change the user's password after forgetting it.

Note that there is a limit of 15 times that requests to the Create User Session endpoint can be made over a 30 minute period. If this limit is exceeded then the endpoint will return Maximum Requests Exceeded result status code. This is a security feature. 

HTTP Request

HTTP Response

HTTP Response Example:

The endpoint terminates an existing user's session to the API by destroying the session based on the session ID given. Once the API has finished being used it is recommended to destroy the session and close off any resources that it was using on the server. If the session is not destroyed then eventually it will expire and be forcably terminated by the server.

HTTP Request

HTTP Response

HTTP Response Example:

The endpoint checks to see if an existing user's session still exists when using the API based on the session ID given. This endpoint can be used to verify an existing session exists before requiring to create a new session, or destroy an existing session.

HTTP Request

HTTP Response

HTTP Response Example:

The endpoint obtains a list of products and the available stock quantity for each product. To use the endpoint the user associated with the session must be a normal user who is assigned to a Facility Permission Role that has the "Data API Product Stock Export" permission set to allow, as well as the Data API project setting labelled "Allow Users To Use Data API" set to YES. If neither of these settings is set correctly then the result status will inform of an access denied error.

The list of product data returned with this endpoint is based on the products that the user associated to the session is allowed to see. This is controlled with the Inventory Permission Role assigned to the user.

Note that there are restrictions on the amount of times that the endpoint can be called per user. The limit is set at 5 requests are allowed within a 30 minute period. If more than 5 requests are made then the endpoint will automatically return a "maximum requests exceeded" error code. This limit is in place for security and server performance reasons. 

HTTP Request

HTTP Response

HTTP Response Example:

The endpoint imports a list of data into a TOTECS project based on the given data type. The data itself must be placed into the Body of the HTTP request in the form of an Ecommerce Standards Document that matches the data type. This endpoint provides the same functionality as if calling a Connector data import to run from within the Data Imports Administration Centre interface.
Note: To obtain the specification for the Ecommerce Standards Document that you are trying to import please contact your TOTECS representative to obtain the details. 

HTTP Request

HTTP Response

HTTP Response Example:

The endpoint imports a product image file into a TOTECS project against a given product. The image must be uploaded in a multi-part HTTP request post form. All parameters in the HTTP request below must be put in the body of the request except for the jsession ID that needs to be placed in the request's URL. Ensure that the filesize of the image is under 2MB. If a JPEG image is being uploaded then make it is set to an RGB colour profile.

HTTP Request

HTTP Response

HTTP Response Example:

The endpoint imports a product attachment file into a TOTECS project against a given product. The attachment must be uploaded in a multi-part HTTP request post form. All parameters in the HTTP request below must be put in the body of the request except for the jsession ID that needs to be placed in the request's URL. Ensure that the filesize of the attachment file is under the 10MB limit.

HTTP Request

HTTP Response

HTTP Response Example:

Below are the codes for the "resultStatus" field that is returned with the response data from API endpoints. The codes denote if the endpoint successfully ran, and if not the reasons why it failed. The codes are based on the Ecommerce Standards Documents codes.