El evento es la parte principal de esta API de ingesta de datos. En este elemento es donde se va a enviar a la plataforma la información del evento generado por cada uno de los dispositivos en tiempo real.
Envío de un único evento
-
Method: POST
-
URL: {baseUrl}/v1/event
-
Body (elemento en formato JSON):
{ "actionId": "CLI_235", "beaconId": "cff92179-dc0a-47da-bd9e-5e9c5b14d251", "beaconTypeId": 1, "timestamp": "2021-03-15T13:34:00.000Z", "lon": -3.45368, "lat": 40.36586, "eventTypeId": 1, "hdop": 1, "speed": 120 }
Descripción de los campos del evento
*** = Campo requerido**
-
actionId * (texto): Identificador único del evento
-
beaconId * (texto): : identificador único de la baliza (por ejemplo, la MAC)
-
beaconTypeId * (número entero): identificador del tipo de baliza. Posibles valores en /beaconTypes. 1 = Vehicle, 2 = Mobile
-
timestamp * (fecha UTC): fecha y hora en formato UTC del momento en el que el evento se ha generado. Es necesario que sea de un máximo de 15 segundos de antiguedad con respecto a la hora UTC. La fecha debe finalizar con el caracter 'Z' que marca que está en UTC
-
lon * (número decimal): longitud de coordenadas de tipo WGS 84 donde se ha generado el evento
-
lat * (número decimal): latitud de coordenadas de tipo WGS 84 donde se ha generado el evento
-
eventTypeId * (número entero): identificador del tipo de evento. Posibles valores en /eventTypes. 1 = VAC en camino, 2 = VAC en intervención, 3 = VAC intervención finalizada
-
hdop * (número entero): valor DOP para determinar la calidad de la información del GPS. Más información aquí
-
speed * (número decimal): velocidad en kilómetros por hora a la que se encuentra el elemento en el momento que envía el evento
Requisitos
Con objeto de mantener la calidad de los mensajes se aplicarán los siguientes requisitos al contenido de los mensajes:
-
La posición geográfica debe estar contenida en el territorio español
-
Se establece a continuación el orden, cantidad y frecuencia de los mensajes:
- Eventos de tipo VAC en camino, un único mensaje.
- Eventos de tipo VAC en intervención, tantos mensajes como dure la intervención con una frecuencia de 100 segundos entre ellos.
- Eventos de tipo VAC intervención finalizada, un único mensaje.
-
La posición proporcionada por el GPS no debe tener un error mayor a 5 metros
-
Se aceptaran eventos con una antigüedad máxima de 15 segundos con respecto a la hora UTC, y que no sea un dato a futuro. En caso de no cumplirse, se recibirá un: HTTP Status: 400 Bad Request Error code: 10
Errores
En este caso de uso, uno de los posibles errores es el error 13 - There is an error in one or more elements y la respuesta obtenida tendrá un valor en el errorElements que nos indicará los campos donde está el error.
La estructura del elemento errorElements es la siguiente:
-
position: La posición del elemento erróneo dentro de la lista enviada. En el caso de ser un único elemento el valor será 0.
-
actionId: Es el valor del actionId del elemento erróneo.
-
errors: Es un array de cadenas de texto en el que se explican detalladamente cada uno de los errores que se han detectado en cada uno de los elementos.
Aquí podemos ver un ejemplo de la respuesta:
{
"status": 400,
"code": 13,
"message": "There is an error in one or more elements",
"errorElements": [
{
"position": 0,
"actionId": "860525f3-d27b-412b-9d79-7f2ef341e663",
"errors": [
"eventTypeId: must be less than or equal to 3",
"hdop: must be greater than or equal to 0"
]
},
{
"position": 1,
"actionId": "017bdb38-6151-4f76-bd9e-34376db36efa",
"errors": [
"speed: must be greater than or equal to 0",
"beaconTypeId: must be less than or equal to 2"
]
}
]
}