The documentation for this API provides a detailed description of the available endpoints with examples of the responses obtained, as well as information
about their usage.
Some prior considerations to take into account are:
-
The API uses JSON Web Tokens for authentication.
-
API requests must be made with GET o POST requests as appropriate.
-
All responses that are not returned with an HTTP 200
code can be considered an error.
-
All responses are returned in JSON format.
Version
The versioning of the API is determined in the URL itself. For example, for
version 1 we will get the following URL:
{baseUrl}/v1/xxx....
Authentication
-
As a previous step to obtaining the token, you must have the security
certificate and that the IP is on the allowed list.
-
The cn of the user registered in the system must be sent as a parameter.
{baseUrl}/v1/token?cn=prueba
-
If the authentication is valid, a response is obtained with the date and time when it was generated, when it expires and the token itself.
{ "issuedAt": "2021-04-01T09:09:16.284", "expiration": "2021-04-02T09:09:16.284", "token": "Bearer eyJhbGciOiJIUzUxMiJ9.e......." }
-
Also, if a request is made with an expired token, an HTTP 400 – Bad Request error is received with the response as in the following example. A new token must be requested to continue making requests to the API.
{ "status": 400, "code": 6, "message": "Expired token received" }
-
To make requests to the API endpoints, an attribute must be attached to the request headers in the header (Authorization) and its value will be Bearer (the type of token obtained) plus the value of the token that you have obtained separated by a space. For example:
Bearer eyJhbGciOiJIUzUxMiJ9.eyJqdGkiOiJDTW9iaWxpdHkzLjAiLCJzdWIiOiJwcnVlYmEiLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwiaWF0IoxNjE2NDIxMDYyLCJleHAiOjE2MTY0MjQ2NjJ9.N8KimN9_IgtjXX2Wv-rXLKK929mavlkaakxY_NzHVFgN9DWT8bqRVeTaBgL5GbzDfZSPZXDutoVwjdbTEx3FbA
Errors
As stated above, all HTTP responses other than 200 – OK, can be considered invalid. The format of the error response is like the following example:
{
"status": 401,
"code": 1,
"message": "User not found or valid"
}
These errors will have three main categories:
Authentication Error
-
HTTP Status: 401 - Unauthorized
Code Message 1 User not found or valid
Client Error
-
HTTP Status: 400 - Bad Request
Code Message 0 Authenticate 2 Entity ID not found 3 Missing required property 4 The entity received cannot be proccessed 5 Incorrect token received 6 Expired token received 7 There is an error with the token provided. Please request a new one 8 No token received 9 Required request body is missing 10 Event is marked as expired by timestamp
Server Error
-
HTTP Status: 500 - Internal Server Error
Code Message 11 Internal error