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/*






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 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 as a Unix timestamp.

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


The default 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. 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:

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

You get:


Notes »

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.

Video: How to use Handy API v1 with Postman

We prefer convention over configuration, so we use default methods for the CRUDL actions.

CREATE: POST

READ: GET

UPDATE: PUT

DELETE: DELETE

INDEX: GET


The user types and roles that are configured in Handy and you can use in your requests are the following:

User types:

1. SALES

2. ROUTESALE

3. PROMO


User roles:

2. ROLE_COMPANY_ADMIN

3. ROLE_SALES_SUPERVISOR

4. ROLE_SALES

5. ROLE_KEY_ACCOUNT_MANAGER


Endpoints »