To use our API you will need a token so that we can identify you in all the requests. All requests to our API need a Bearer Token for Authorization.
You will need to generate a token for your Handy user. The user must have the Company admin role in order to have full permission to all the endpoints.
You must log in to the web portal, go to the menu > users, then find your user and go to edit your data. You just have to click on the generate token button.
Your token will not expire unless you revoke it.
If you believe that the security of your current token is compromised, you must revoke the current token and generate a new one.
You must log in to the web portal, go to the menu > users, then find your user and go to edit your data. You just have to click on the revoke token button.
Tokens are personal for each user.
Only administrator users will be able to generate and revoke tokens to use the API. If you are an administrator user, you will be able to see the tokens of the other administrator users, but you will NOT be able to generate them or revoke their token.
The API limits the number of requests for your application. Such limits are managed as an allowed number of requests per time window. If you exceed the number of requests allowed in the time window you will get '429 Too Many Requests' response code and the following headers:
X-RateLimit-Limit: Maximum number of operations allowed in the current window.
X-RateLimit-Reset: Time when rate limit window will be reset as a Unix timestamp.
X-RateLimit-Remaining: Number of operations left in the current window.
The default rate limit is 500 requests per minute.
Many times when we are making requests to an API there will be many results to return, for this reason we paginate the results to make sure responses are faster to handle.
By default, the max param is 10, so we offer 10 results per page. The results will be sorted by the event creation date. Depending if the event was created in the mobile app or in the web app, the corresponding date field will be used. When the page is not specified in the path parameters, the first page will be returned.
We have added a map named "Pagination" with several useful links for you if you are doing an integration. In these, you can check the number of records that your query has, and also the total pages, the current page, the first page, the last, the next and the previous. This map will be the first item that you find on the response json and the second item will be named as the resource and contains the results.
Here is an example:
We use the id as identifier for the objects, except for products, customers and price lists. You can notice that on the endpoint's paths. So, for example, if you want to create a route, you need to specify the products with their codes.
If you need to use some special character in the path params you must escape them in UTF-8 encoding. For example: '%2F' instead of '/'. Here is a complete list of special characters.
For dates you must use dd/MM/yyyy HH:mm:ss format.
We prefer convention over configuration, so we use default methods for the CRUDL actions.
The user types and roles that are configured in Handy and you can use in your requests are the following: