API Essentials
Dive into the specifics of each API endpoint by checking out our complete documentation.
Introduction
Welcome to the API Reference Guide. This document provides comprehensive information about the API, including data types, parameters, and error codes.
Our api is version-managed, so it is important to read the corresponding documentation. The version references specify which URL to use.
All endpoints have a restriction on the number of calls made in a specific time. This means that the same endpoint cannot be called more than once if the defined time has not yet elapsed. For example, the geofence report can only be consumed once every 60 seconds.
Data Types
String: A sequence of characters.
Datetime: A JSON datetime format. YYYY-MM-DDTHH:MM:SS
Integer: A whole number without a fractional part.
Float: A number that includes a decimal point.
Boolean: A true or false value.
Array: A list of values.
Object: A collection of key-value pairs.
General Parameters
Authentication
API Key: A unique key required for authenticating API requests.
Token: A token generated upon login, valid for 24 hours.
Pagination
limit: The maximum number of items to return.
offset: The number of items to skip before starting to collect the result set.
Filtering
startDate: The beginning date for filtering results.
endDate: The end date for filtering results.
Error Codes
200 Success
The request was successful, and the server returned the expected response.
400 Bad Request
The server could not understand the request due to invalid syntax.
401 Unauthorized
The client must authenticate itself to get the requested response.
404 Not Found
The server can not find the requested resource.
429 Too Many Requests
You are making more calls than allowed to the endpoint, you must wait the defined time to retry.
500 Internal Server Error
The server has encountered a situation it doesn't know how to handle.
Error codes
When the response to the request is different from 200 successfully, the result will usually be a structure like the following:
export interface IErrorResponseApi {
code: APICLIENT_RESPONSE_CODE;
message: string;
}These are general errors, then in each EP more error codes can be specified according to the business logic being executed.
OK
No errors
001
Invalid credentials.
002
General server error. Please verify your data or contact support.
100
It is mandatory to specify a valid time range. Read the endpoint doc to know the limitations for the endpoint.
export enum APICLIENT_RESPONSE_CODE {
OK = 'OK',
invalid_credentials = '001',
general_server_error = '002',
invalid_date_range = '100'
}General Structures
All endpoints receive in the body a json structure with specific data for the endpoint as well as general information by default.
It is possible to perform paging automatically when the structure allows it through the IPagination interface.
For example, to consume the EP of the fence report, it receives a structure as follows:
export interface IApiDev_RptGeofenceFilter{
pagination?: IPagination;
devices?: string[];
geofences?: string[];
idletime?: number;
startdate: string;
enddate: string;
}
And it allows you to specify the paging through the following structure:
export interface IPagination {
limit: number,
offset: number
}In the interfaces, all fields containing a "?" mean that they are optional, which can be sent or not. But all those fields that do not have the "?" must be sent correctly.
Pagination is optional unless otherwise specified as defined above with "?".
Most EP results contain a field called "full_count", this field will contain the total number of records, so you can programmatically perform the corresponding pagination.
{
"pagination":{
"limit":0,
"offset":0
},
"devices": [],
"geofences": [],
"idletime": null,
"startdate": "2024-06-01",
"endate": "2024-06-22"
}
This example, performs the pagination of 10 records per page and is requesting the first page (0), if you want to get the page number 4, you should put in "offset" the value "3", if you want to get more records per page just change the corresponding value. Page value - 1 (first page is 0).
As explained above, pagination is optional unless otherwise specified, when pagination is not sent, EP will return all records according to the selected filters.
IMPORTANT: When you make a request to an endpoint, the system caches the data, so if you make the same request again, the system will return the same data, this way we optimize and guarantee that you do not have delays in receiving the information.
The life time of the cache is 300 seconds, once this time expires, the cache is deleted.
Last updated