|
|
# Identificación en el servicio
|
|
|
|
|
|
Para llevar a cabo las operaciones del API es necesario obtener un token de sesión que caducará de forma aleatoria a lo largo de la misma. La operación que permite obtenerlo es **/api/1.0/getToken** que devuelve el siguiente resultado:
|
|
|
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"info_code": 0,
|
|
|
"info_desc": "OK",
|
|
|
"data": [
|
|
|
{
|
|
|
"token": "28a9e96167a6ee0f84bb9c46e8a3b381032f7d9de59ce882539db044e4ee691f"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
El proceso de autenticación está basado en certificados digitales de cliente. Para la realización de pruebas y posterior pase a producción, el cliente deberá cumplimentar la documentación proporcionada en la que se le solicitan los datos necesarios de la empresa que vaya a consumir los servicios. El certificado será emitido por la PKI de la plataforma y entregado físicamente al responsable del mismo.
|
|
|
|
|
|
En caso de no tener permisos tanto en esta operación como en el envío de eventos, se devolverá un mensaje del tipo
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"info_code": 99,
|
|
|
"info_desc": "Authorization error",
|
|
|
"data": []
|
|
|
}
|
|
|
``` |
|
|
La documentación de esta API ofrece una descripción detallada de los
|
|
|
métodos disponibles con ejemplos de las respuestas obtenidas, así como
|
|
|
información acerca del uso.
|
|
|
|
|
|
Algunas consideraciones previas a tener en cuenta son:
|
|
|
|
|
|
- La API utiliza **JSON Web Tokens** para la autentificación.
|
|
|
|
|
|
- Las peticiones de la API deben ser realizadas con **peticiones GET o
|
|
|
POST** según el caso.
|
|
|
|
|
|
- Se pueden considerar todas las respuestas que no sean devueltas con
|
|
|
un código HTTP 200 como un **error**.
|
|
|
|
|
|
- Todas las respuestas son en **formato JSON**.
|
|
|
|
|
|
## Versión
|
|
|
|
|
|
El versionado de la API se determina en la propia URL. Por ejemplo, para la
|
|
|
versión 1 obtendremos la siguiente URL:
|
|
|
|
|
|
> {baseUrl}/<mark>v1</mark>/xxx....
|
|
|
|
|
|
## Autentificación
|
|
|
|
|
|
- Como paso previo a la obtención del token, se debe poseer el certificado de seguridad y que **la IP esté en la lista de permitidas**.
|
|
|
|
|
|
- El **cn** que está contenido en el certificado que se utiliza es el que la aplicación utiliza para comprobar si existe en el registro de usuarios.
|
|
|
|
|
|
> {baseUrl}/v1/<mark>token</mark>
|
|
|
|
|
|
- Si la autentificación es válida, se obtiene una respuesta con la fecha y hora en formato UTC en la que se ha generado, en la que expira y el propio token.
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"issuedAt": "2021-04-01T09:09:16.284Z",
|
|
|
"expiration": "2021-04-02T09:09:16.284Z",
|
|
|
"token": "Bearer eyJhbGciOiJIUzUxMiJ9.e......."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
- Además, si se realiza una petición con un token expirado se recibe un error **HTTP 400 – Bad Request** con la respuesta como en el siguiente ejemplo. Se debe solicitar un nuevo token para continuar realizando peticiones a la API.
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"status": 400,
|
|
|
"code": 6,
|
|
|
"message": "Expired token received"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
- Para realizar peticiones a los *endpoints* de la API se debe adjuntar en las cabeceras de la petición un atributo en la cabecera (**Authorization**) y su valor será Bearer (el tipo de token obtenido) más el valor del token que has obtenido separado por un espacio. Por ejemplo:
|
|
|
|
|
|
```
|
|
|
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">
|
|
|
|