|
|
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.
|
|
|
|
|
|
To carry out the API operations, it is necessary to obtain a session token that will expire randomly throughout the session. The operation that allows to obtain it is**/api/1.0/getToken** with the results:
|
|
|
Some prior considerations to take into account are:
|
|
|
|
|
|
- The API uses **JSON Web Tokens** for authentication.
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"info_code": 0,
|
|
|
"info_desc": "OK",
|
|
|
"data": [
|
|
|
{
|
|
|
"token": "28a9e96167a6ee0f84bb9c46e8a3b381032f7d9de59ce882539db044e4ee691f"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
The authentication process is based on client digital certificates. To carry out tests and later go to production, the client must complete the documentation provided in which the necessary data of the company that is going to consume the services is requested. The certificate will be issued by the PKI of the platform and physically delivered to the person responsible for it.
|
|
|
- API requests must be made with **GET o
|
|
|
POST requests** as appropriate.
|
|
|
|
|
|
In case of not having permissions both in this operation and in the sending of events, a message of the type will be returned
|
|
|
- All responses that are not returned with an HTTP 200
|
|
|
|
|
|
code can be considered an **error**.
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"info_code": 99,
|
|
|
"info_desc": "Authorization error",
|
|
|
"data": []
|
|
|
}
|
|
|
``` |
|
|
\ No newline at end of file |
|
|
- 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}/<mark>v1</mark>/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** that is contained in the certificate that is used is the one that the application uses to check if it exists in the user registry.
|
|
|
|
|
|
> {baseUrl}/v1/token
|
|
|
|
|
|
- If the authentication is valid, a response is obtained with the date and time in UTC format when it was generated, when it expires and the token itself.
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"issuedAt": "2021-04-01T09:09:16.284Z",
|
|
|
"expiration": "2021-04-02T09:09:16.284Z",
|
|
|
"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.
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"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
|
|
|
```
|
|
|
|
|
|
<img title="" src="https://i.loli.net/2021/03/24/N759fRtgE2PWn8h.png" alt="2021-03-24-13-21-32-image.png" data-align="center">
|
|
|
|
|
|
## Swagger
|
|
|
|
|
|
The application has a Swagger auto-generated by the code itself where the different *endpoints* can be found.
|
|
|
|
|
|
> {baseUrl}/swagger-ui/index.html |