Handy API v2 Developer Documentation

Using the Handy API you can perform a manual integration between Handy and your current management system or ERP.

The full endpoint for the current version of the API is https://app.handy.la/api/v2/*

You can also learn about specific use cases for the API with our API guide.

Authentication »

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.

How to generate a token?

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.

How to use the token?

You need to add a header named Authorization to your request, and the value of the header must be Bearer TOKEN, where you replace TOKEN with your API token.

How to revoke a token?

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.

Who can generate and revoke tokens?

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.

Rate Limiting »

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:

Rate Limit Headers

X-RateLimit-Limit: Maximum number of operations allowed in the current window.

X-RateLimit-Reset: Time when rate limit window will be reset, expressed as a Unix timestamp.

X-RateLimit-Remaining: Number of operations left in the current time window.

The rate limit is 500 requests per minute.

Pagination »

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, ascending, so older events come first. 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. With:

GET https://app.handy.la/api/v2/salesOrder

You get:

Notes »

We use the database ID as identifier for the objects, except for products, customers and price lists. You can see 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: '%20' instead of the space character ' '. Here is a complete list of special characters.

Please notice that you cannot use the slash "/" character in your products' code because it's a reserved character for URLs. You can learn more about it here.

For dates, you must use dd/MM/yyyy HH:mm:ss format. That is, two digit months (01, instead of 1) and 24 hour format (16:00 instead of 04:00 p.m.)

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:

User types:





User roles:





The sales types that are configured in Handy and you can use in your requests to filter your orders are the following:

Sales types:

PRESALE: Orders created by delivery and presales users.

ROUTESALE: Orders created by route sales users.

Endpoints »