Getting Started
In this article you will learn important information about the Komet Sales API, how to create tokens and test different methods.
What is the Komet Sales API?
The Komet Sales API helps you develop additional tools directly tied to the system. This will allow growers, customers or 3rd parties (such as other technology companies or your in-house developers) to expand and build on the Komet Sales platform and access the Komet Sales data using HTTP and JSON.
The API makes creating web and desktop applications that integrate with Komet Sales easy. Some potential uses include:
Creating a customized e-commerce solution that uses Komet Sales as the backend for order processing and inventory management.
Allowing the growers to integrate Komet Sales directly into their systems to review/confirm orders.
Integrating with your CRM system.
Interacting with other 3rd party systems that your company uses.
Important Considerations
The Komet Sales API has a single point of entry:Â https://api.kometsales.com/api/
All requests must be submitted using SSL.
You must send an authentication token per request.
Use the login method to get your token and save it into your application. You will be able to use the same token from this point forward.
You can create tokens not linked to a user and limit access to specific API methods.
The API is limited to 1,000 requests per user per day, based on the company's plan in Komet Sales. In other words, if the company is paying for three users in Komet Sales, your external system can only call the Komet Sales API 3,000 times (3 X 1,000) per day.
The size limit for any request is 64kb.
Some methods require you to upload the file in bytes. When this is required, the byte size limit is 20MB, and the way to convert the files to bytes depends on the language you are using.
Create Tokens
Tokens are the authentication mechanism that allows access to the API methods for the company. To set up a token, please follow these instructions:
Go to Setup > Settings and click on the "Tokens" link.
If a new token needs to be created, click the New Token green button on the window's right-hand side.
Select which Token Type needs to be added: Company, Customer, or Vendor.
Input the information requested in order to complete the process:
Enter the token description, for example, "managing inventory".
Select the API method needed from the list available, in this case, "inventory.add".
Click the Generate button, and the system will create a token of numbers and letters. If the token was created for a Customer, the token must be sent to the customer.
Click on Save.
If the token needs to be edited, go to the "Actions" column and click "Edit" and Save.
Items in bold are required.
Date and time values are of the form YYYY-MM-DD HH:MM:SS.
All time values are returned in UTC timezone. You can learn more about UTC here:Â http://en.wikipedia.org/wiki/Coordinated_Universal_Time.
Booleans are either 1 (true) or 0 (false).
HTTP Status Codes
Some of the responses may contain HTTP status codes as the following:
Code | Status | Description |
---|---|---|
200 | OK | Standard response for successful HTTP requests. |
201 | Created | The request has been fulfilled, resulting in the creation of a new resource. |
204 | No Content | The server successfully processed the request, and is not returning any content. |
400 | Bad Request | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing). |
401 | Unauthorized | Authentication is required and has failed or has not yet been provided. |
403 | Forbidden | The request contained valid data and was understood by the server, but the server is refusing action. This may be due to the user not having the necessary permissions for a resource or needing an account of some sort, or attempting a prohibited action |
404 | Not Found | The requested resource could not be found but may be available in the future. |
408 | Timeout | The server timed out waiting for the request. |
429 | Too Many Requests | You have exceeded the rate limit. |
500 | Server Error | Malfunctioning script, server configuration error or similar. |
Integrations for Vendors
Komet is integrated directly with cargo agencies and grower systems such as Unosof, Ventures, Vida 18, Cargo Master, and others. You could also connect Komet with your system using the next methods.
Need | Available |
---|---|
Obtain a list of box types | The method Get a list of Box-Types allows to obtain a list of box types sorted by box type code. |
Obtain a list of products | The method Get a Product List allows to obtain a list of products with its description. |
Create Purchase Orders | The method Create a Purchase Order allows to create Purchase Orders based on Prebooks. |
Add products to an AWB | The method Add Purchase Order Items to an AWB allows adding product lines of a Purchase Order to an AWB. |
Delete items from a Purchase Order | Through the method Delete an Item from a Purchase Order users can delete products from a Purchase Order. |
Obtain a list of Purchase Orders | The method Get a list of Purchase Orders returns a list of Purchase Orders with its corresponding details. |
Change Box Codes | .The method Change Box Codes allows changing one or more box codes. |
Create Purchase Orders with assorted product | Through the method Create a Purchase Order with Breakdowns users can create Purchase Orders with assorted products of Prebooks in units. |
Integrations for Prebooks and Purchase Orders
Need | Available Methods |
---|---|
Create/Update Prebooks | The method prebook.create allows users to add a Prebook to Komet Sales and update existing Prebooks. |
Delete Prebooks | With the method prebook.item.delete users can delete Prebooks from Komet Sales. In case this method is used with a vendor token, the system will update the quantities to 0. |
Obtain a list of Prebooks created in Komet | This method returns a list of Prebooks with their corresponding details. |
Create Purchase Orders | The method Create a Purchase Order allows to create Purchase Orders based on Prebooks. |
Add items to a AWB | The method Add Purchase Order Items to an AWB allows to add product lines of a Purchase Order to an AWB. |
Delete items from Purchase Orders | Through the method Delete an Item from a Purchase Order users can delete products from a Purchase Order. |
Obtain a list of Purchase Orders created in Komet | The method Get a list of Purchase Orders returns a list of Purchase Orders with its corresponding details. |
Create Purchase Orders with assorted product | Through the method Create a Purchase Order with Breakdowns users can create Purchase Orders with assorted products of Prebooks in units. |
List of API Methods
Test an API Method
In the next example, we use Postman to test API methods. Postman is an API Development Environment. Other API Development Environments include Insomnia, SoapUI, curl, etc.
Within Komet, there are two basic types of requests: POST and GET.
Test POST methods
POST methods send data to a server to create/update a resource.
To test a POST method, do the following steps:
Open Postman.
Select the request type.
Select the format. This can be selected from the Body Type. In this case, is JSON.
Click on the Body tab. Check the raw option. The "Text" dropdown menu and select JSON (application/json).
To enter the parameters, you can copy and paste the sample request. Click on Beautify so the format is corrected.
Verify the parameters, and once you have finished, click on Send. The method should return the results, as shown on the documentation response sample.
Â
Test GET methods
GET methods are used to request data from a specified resource.
To test a GET method, do the following steps:
Open Postman.
Select the request type.
Enter the URL that corresponds to the request.
For GET methods, you must enter the URL parameters.
Click on Params. Proceed to enter each input parameter required (e.g. authentication token). Once you have finished, click on Send.
Some methods will require additional information on the header, such as X-SALES-CHANNEL and X-ACCOUNT. This information must be entered the same way the input parameters are entered.
Related Content
-
Delete a Prebook 1.0 (API)
-
-
Getting Started (API)
-
-
Data Import (Knowledge Base)