Data API Login

Contents

  1. Prerequisites
  2. Overview
  3. Endpoint: Create User Session
  4. Endpoint: Destroy User Session
  5. Endpoint: Validate User Session
  6. Endpoint: Export Product Stock Levels
  7. Endpoint: Import Data
  8. Endpoint: Upload Product Image
  9. Endpoint: Upload Product Attachment
  10. Appendix I: Result Status Codes

This document describes the Application Programming Interface (API) that allows data to be imported into a project on the TOTECS platform, as well as exported. The API is used to allow third party software to programmatically interact with a TOTECS project without requiring human interaction to save, or extract out data.

Prerequisites

Please ensure that you have read and understand the following topic links before reading on.

Overview

The Application Programming Interface (API) allows third party software external to the TOTECS platform to have the ability manage data within a TOTECS project. 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, 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.

Endpoint: Create User Session

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 Method GET
HTTP URL https://[secure.totecs.domain]/dataapi/create_user_session
   
Parameters Data Type Mandatory Description
pkey STRING Yes Key of the TOTECS project to create a session with.
user STRING Yes Login ID of the ser
pass STRING Yes Password of the user
major_version INTEGER No Major version number to use for the API. If no version is given then the latest version of the API will be used to return data.

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
sessionID STRING ID of the session if it was successfully created.
appMajorVersion INTEGER Major version number of the endpoint that was used to return the response data.
appMinorVersion INTEGER Minor version number of the endpoint that was used to return the response data.
version INTEGER Version of the Ecommerce Standards Document that the response was returned in.
resultStatus INTEGER Status of trying to create the session. See the Appendix I for the list of possible status codes.
message STRING Messsage describing the results of calling the endpoint.
result ENUM DEPRECATED: either "success", or "failure". If successful then a user session was successfully created.
api_version STRING DEPRECATED: Version of the data API handling the response.
result_code STRING

DEPRECATED: 
either:
SUCCESS
ERROR_INVALID_CREDENTIALS

jsessionid STRING DEPRECATED: ID of the session if it was successfully created.
product_image_folder_key STRING Name of the key used to allow product images to be uploaded through the API. Only returned when a session is created for an administrator user.
product_attachment_folder_key STRING Name of the key used to allow product attachments to be uploaded through the API. Only returned when a session is created for an administrator user.

 

HTTP Response Example:

{"resultStatus":1,"result":"success","majorVersion":1,"minorVersion":0, "api_version":"1.0.0.0", "result_code":"SUCCESS", "message":"The user session has successfully been created.", "sessionID":"12345678901234567890", "jsessionid":"12345678901234567890", "product_image_folder_key":"product_image", "product_attachment_folder_key":"product_attachment"}

Endpoint: Destroy User Session

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 Method POST
HTTP URL https://[secure.totecs.domain]/dataapi/destroy_user_session/[sessionid]
     
Parameters Data Type Description
sessionid STRING ID of the user's session.
pkey STRING Key of the TOTECS project.

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
appMajorVersion INTEGER Major version number of the endpoint that was used to return the response data.
appMinorVersion INTEGER Minor version number of the endpoint that was used to return the response data.
version INTEGER Version of the Ecommerce Standards Document that response data was returned as.
resultStatus INTEGER Status of trying to destroy the session. See Appendix I for the list of possible status codes.
message STRING Description to match the result code.
result ENUM DEPRECATED: returns 'success'
api_version STRING DEPRECATED:Version of the data API handling the response.
result_code STRING

DEPRECATED: SUCCESS

 

HTTP Response Example:

{"appMajorVersion":1,"appMinorVersion":0, "version":1,"result_status":1,"result":"success", "api_version":"1.0.0.0", "result_code":"SUCCESS", "message":"The user session has successfully been destroyed."}

Endpoint: Validate User Session

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 Method GET
HTTP URL https://[secure.totecs.domain]/dataapi/validate_user_session/[sessionid]
     
Parameters Data Type Description
sessionid STRING ID of the user's session
pkey STRING Key of the TOTECS project.

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
appMajorVersion INTEGER Major version number of the endpoint that was used to return the response data.
appMinorVersion INTEGER Minor version number of the endpoint that was used to return the response data.
version INTEGER Version of the Ecommerce Standards Document that response data was returned as.
resultStatus INTEGER Status of trying to validate the session. See Appendix I for the list of possible status codes.
session_valid ENUM Either 'Y' or 'N'. If set to Y then the session is still valid.
message STRING Description to match the result code.
result ENUM returns 'success'
api_version STRING DEPRECATED: Version of the data API handling the response.
result_code STRING DEPRECATED: SUCCESS
jsessionid STRING DEPRECATED: ID of the session if it still exists, otherwise it is set as empty.

 

HTTP Response Example:

{"appMajorVersion":1,"appMinorVersion":0,"version":1,"resultStatus":1,"result":"success", "api_version":"1.0.0.0", "result_code":"SUCCESS", "message":"The user session has successfully been validated.", "sessionID":"12345678901234567890", "jsessionid":"12345678901234567890", "session_valid":"Y"}

Endpoint: Export Product Stock Levels

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 Method POST
HTTP URL https://[secure.totecs.domain]/dataapi/export_product_stock_levels/[sessionid]
     
Parameters Data Type Description
sessionid STRING ID of the user's session
pkey STRING Key of the TOTECS project.

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
appMajorVersion INTEGER Major version number of the endpoint that was used to return the response data.
appMinorVersion INTEGER Minor version number of the endpoint that was used to return the response data.
version INTEGER Version of the Ecommerce Standards Document that response data was returned as.
resultStatus INTEGER Status of trying to export the data. See Appendix I for the list of possible status codes.
message STRING Description to match the result code.
totalDataRecords INTEGER Total number of data records returned in the response.
dataRecords ARRAY Array containing product stock quantity records.
Product Data Record Params
keyProductID STRING Unique Key ID of the product
productCode STRING Code of the product
productName STRING Name of the product.
qtyAvailable DECIMAL Quantity of the product stock available, based on each unit of the product.

 

HTTP Response Example:

{"appMajorVersion":1,"appMinorVersion":0,"version":1,"resultStatus":1, "message":"The data has successfully been obtained.", "totalDataRecords":2,"dataRecords":[{"keyProductID":"1","productCode":"EXPROD1","productName":"Example product 1","qtyAvailable":25.0},{"keyProductID":"2","productCode":"EXPROD2","productName":"Example product 2","qtyAvailable":13.0}]}

Endpoint: Import Data

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 Method POST
HTTP URL https://[secure.totecs.domain]/dataapi/import_data/[sessionid]/[import_type_id]
     
Parameters Data Type Description
sessionid STRING ID of the user's session
import_type_id ENUM Either:
9 - Taxcodes
10 - Products
11 - Product Price Levels
12 - Product Price Level Pricing
13 - Customer Accounts
16 - Sales Representative IDs
17 - Product Categories
18 - Customer Account Addresses
19 - Product Stock Levels
20 - Customer Account Product Contracts
21 - Product Customer Account Pricing
22 - Product Alternate Codes
23 - Product Price Level Quantity Pricing
24 - Product Flags
25 - Product Kits
30 - Locations and Location Products
31 - Product Attributes
32 - Product Combinations

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
result ENUM returns either 'success', or 'failure' based on if the data imports successfully or not.
api_version STRING Version of the data API handling the response.
message_code STRING

Either:
SUCCESS
SESSION_NOT_VALID - returned if the API session is no longer exists, or has been destroyed on the server.
SESSION_PERMISSION_DENIED - returned if the administrator user associated the session does not have permission to user the API.
DATA_IMPORT_BUSY - returned if another data import is already running. Only one data import can run at a time to ensure that data conflicts do not occur.
DATA_IMPORT_STATUS_UNDETERMINED - returned if an unknown error occurred while processing the data,

message STRING Description to match the result code.

 

HTTP Response Example:

{"result":"success", "api_version":"1.0.0.0", "result_code":"SUCCESS", "message":"","message_code":"SUCCESS"}

Endpoint: Upload Product Image

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 Method POST
HTTP URL https://[secure.totecs.domain]/view;jsessionid=[sessionid]?
     
Parameters Data Type Description
sessionid STRING ID of the user's session
command STRING set to "upload_item"
savefile STRING name of the image file
savefileext STRING extension of the image file
saveid STRING Key of the product image folder that was obtained from the Create User Session endpoint in the API.
follow STRING set to "util_api_rest"
util_api_rest_action STRING set to "upload_product_image"
accounting_product_id STRING Unique key of the product set when the product was imported into the TOTECS project.
accounting_product_image_id STRING Unique key associated with the product image being uploaded
image_title STRING [optional] title of the image to describe the file.
image_description STRING [optional] description of the image file

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
result ENUM returns either 'success', or 'failure' based on if the product image imported or not.
api_version STRING Version of the data API handling the response.
result_code STRING

Either:
SUCCESS
ERROR_DATA_PROCESSING - returned if the image could not be uploaded

message STRING Description to match the result code.

 

HTTP Response Example:

{"result":"success", "api_version":"1.0.0.0", "result_code":"SUCCESS", "message":"The product image has been successfully uploaded.","message_code":"SUCCESS"}

Endpoint: Upload Product Attachment

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 Method POST
HTTP URL https://[secure.totecs.domain]/view;jsessionid=[sessionid]?
     
Parameters Data Type Description
sessionid STRING ID of the user's session
command STRING set to "upload_item"
savefile STRING name of the attachment file
savefileext STRING extension of the attachment file
saveid STRING Key of the product attachment folder that was obtained from the Create User Session endpoint in the API.
follow STRING set to "util_api_rest"
util_api_rest_action STRING set to "upload_product_attachment"
accounting_product_id STRING Unique key of the product set when the product was imported into the TOTECS project.
accounting_product_attachment_id STRING Unique key associated with the product attachment being uploaded
attachment_title STRING [optional] title of the attachment to describe the file.

 

HTTP Response

Response Data Type JSON
     
Parameters Data Type Description
result ENUM returns either 'success', or 'failure' based on if the product attachment imported or not.
api_version STRING Version of the data API handling the response.
result_code STRING

Either:
SUCCESS
ERROR_DATA_PROCESSING - returned if the attachment could not be uploaded

message STRING Description to match the result code.

 

HTTP Response Example:

{"result":"success", "api_version":"1.0.0.0", "result_code":"SUCCESS", "message":"The product attachment has been successfully uploaded.","message_code":"SUCCESS"}

Appendix I: Result Status Codes

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.

Result Status Code Result Status Description
1 RESULT_SUCCESS A successful response was obtained.
2 RESULT_ERROR An unspecified error occurred when generating the response.
3 RESULT_ERROR_UNKNOWN An unknown error occurred when generating the response.
4 RESULT_ERROR_DATA_SOURCE_CONNECTION_MISSING An error occurred when trying to access the location where the data is stored.
5 RESULT_ERROR_DATA_SOURCE_CONNECTION_LOST An error occurred while accessing where the data is stored due to the connection being severed/lost.
6 RESULT_ERROR_DATA_SOURCE_INVALID_CREDENTIALS An error occurred because invalid credentials were given when trying to access the data where it is stored.
7 RESULT_ERROR_DATA_SOURCE_PROCESSING An error occurred while trying to process the data that was being accessed.
8 RESULT_ERROR_DATA_SOURCE_INVALID_DATA An error occurred while trying to process the data that was being accessed, due to incorrect or missing information required to correctly obtain the data.
9 RESULT_ERROR_CONNECTOR_INVALID_CREDENTIALS An error occurred when trying obtain the data through a connecting application due to invalid credentials given to the connecting application.
10 RESULT_ERROR_CONNECTOR_PROCESSING An error occurred when trying obtain the data through a connecting application due to connecting application failing to process the data.
11 RESULT_ERROR_CONNECTOR_INVALID_DATA An error occurred when trying obtain the data through a connecting application due to connecting application being given incorrect or missing information.
12 RESULT_ERROR_CONNECTOR_INCORRECT_CONFIGURATION An error occurred when trying obtain the data through a connecting application due to connecting application being incorrectly configured.
13 RESULT_ERROR_DATA_SOURCE_PERMISSION_DENIED An error occurred while trying to obtain the data since permission was denied for accessing the data.
14 RESULT_ERROR_DATA_SOURCE_MAXIMUM_REQUESTS_EXCEEDED An error occurred while trying to obtain the data since a the amount of requests to obtain the data has exceeded the maximum allowed amount of times over a given period.