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 }
Envío de múltiples eventos
Este endpoint permite el envío de múltiples eventos al mismo tiempo. Todos ellos deben cumplir con los mismos requisitos que si fueran enviados individualmente.
-
Method: POST
-
URL: {baseUrl}/v1/events
-
Body (array de elementos en formato JSON):
[ { "actionId": "CLI_235", "beaconId": "00:1B:44:11:3A:B7", "beaconTypeId": 1, "timestamp": "{{$isoTimestamp}}", "lon": -0.979758, "lat": 41.694851, "eventTypeId": 1, "hdop": 1, "speed": 120 }, { "actionId": "CLI_235", "beaconId": "00:1B:44:11:3A:B8", "beaconTypeId": 1, "timestamp": "{{$isoTimestamp}}", "lon": -0.978548, "lat": 41.684751, "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 30 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 una frecuencia de envío de mensajes máxima de un mensaje cada 10 segundos para eventos de tipo VAC en camino y de 100 segundos para tipo VAC en intervención
-
La posición proporcionada por el GPS no debe tener un error mayor a 5 metros
-
Se requiere una antigüedad máxima de 30 segundos con respecto a la hora UTC
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"
]
}
]
}