API Base URL: https://api-platform.vntana.com
For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.
Another feature offered on the VNTANA Platform are Comments. Comments can be added to a number of different entities: Products, Configurators, and Annotations. This feature allows team members to easily communicate, and by utilizing the Admin API you can automatically create Comments on a Product upon the notification of a status change by a Webhook for any future reference if it is known an extra process will need to be deployed in the future.
As with all Admin API processes you must first authenticate. View our Authentication guide for a detailed explanation of the steps involved, or use the below summary to authenticate.
-
Log in using an Authentication Key or email / password.
-
Returns an x-auth-token in the Response Headers.
-
-
Retrieve a list of Organizations and store the needed Organization’s UUID.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1{ ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token } -
This step can be skipped if the Organization UUID is already stored locally.
-
-
Generate a Refresh Token for the Organization.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1234{‘x-auth-token’ : ‘Bearer ‘ + x_auth_token‘organizationUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
-
Retrieve a list of Clients / Folders and store the needed UUID.
-
Pass the x-auth-token in the Request Headers.
-
This step can be skipped if the Client / Folder UUID is already stored locally.
-
-
Generate a Refresh Token for the Client / Folder (Organization Admin / Owner users must skip this step).
-
Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
Create a Comment
To create a comment, you must first determine the entity that the product will be added to and retrieve its UUID. Below are examples of searching for entities, or view our guides on searching Products, Configurators, or Annotations.
The Request is structured as follows:
The Response is structured as follows:
The searches are fuzzy, meaning they return results based on relevance. Unless every Product name is quite unique, you’ll likely have to iterate over the results to match the name exactly.
The Request is structured as follows:
The Response is structured as follows:
The Request is structured as follows:
The Response is structured as follows
Using the Product example, with the Product UUID in hand, you can call the following endpoint, setting entityType to ‘PRODUCT’:
The message parameter is of course the text of the comment itself. This will return the uuid of the comment in the Response body which is needed to edit or delete the comment.
Retrieving Comments
To retrieve the comments of an entity such as Products, you will need to know the entityUuid. Using a Product as an example, use the above Product Search example to retrieve this UUID, then use the following endpoint to pull its comments:
This will return the following Response:
This will return information on both the Comment itself and the entity it is attached to.
Postman Collections
You can test the above endpoints with the following Postman collection. This collection contains everything you need to create or retrieve comments, from authentication to creation. To run the collection as a whole, you will need to deselect the endpoints you do not need or want to run, and ensure the global variables are set in the collections Pre-request Script.
If you would like to run the endpoints individually you must re-enable the X-AUTH-TOKEN header for all endpoints except the login endpoints, and ensure each endpoint has the necessary body and query parameters.