Saltar a contenido

Webhooks

Los Webhooks sirven para integrar data de startrack a otros sitemas en tiempo real por http/https.

A diferencia del API, los Webhooks no requieren que el sistema receptor haga peticiones continuamente (polling).

Startrack reenvía estos datos en tiempo real a la dirección (Webhook URL) que usted defina.

WH: Alertas (alerts)

Si está configurado el Alerts Webhook URL del cliente, sus usuarios pueden configurar reglas que alerten por webhook.

Startrack transmitirá los datos de la alerta por HTTP/HTTPS POST, enviando datos en el BODY

WH: Remote ID (remote_id)

Este campo se usa como un identificador único con el fin de relacionar la información recibida a un dispositivo GPS/vehículo.

Por lo tanto este identificador no debe repetirse entre dos dispositivos.

Este parámetro está vacío por defecto y al momento de modificarse no puede incluir espacios; únicamente letras, números y algunos caracteres especiales como: "-","_","(",")" y ":".

Para editar este campo primero se debe de ir a la unidad y ver la pestaña de "Vehículo".

botones

Luego dar click a la opción "Modificar" y buscar el campo "remote_id".

botones

Colocar el identificador único siguiendo las especificaciones detalladas anteriormente y presionar "Guardar".

O: Alert Data Object

El objeto de tipo Alert siempre tiene estos campos:

campo explicación
eventId Identificador de la alerta
messageId Identificador del tipo de evento/alerta.
vehicle La descripción del vehículo
date La fecha del evento en formato unix (segundos desde 1970 GMT)
place Descripción del lugar. Esto puede incluir el nombre de áreas que el usuario dibuja sobre el mapa.
lat Latitud
lon Longitud
poiContact Datos de contacto de la geocerca
driver Datos del conductor asignado
odometer El valor del odómetro en el momento de la alerta
ignOnTime El valor del horómetro en el momento de la alerta
ruleOwner El nombre del usuario que creó la regla
ruleOwnerId El ID correlativo del usuario que creó la regla
urId El ID correlativo de la regla

El objeto de tipo Alert puede tener estos campos, dependiendo del tipo de alerta (messageId):

campo explicación
event Nombre del evento detectado
poiName Nombre de la geocerca (POI) donde se detectó el incedio (similar a place, pero solo tiene el nombre del área y no mas
poiNames Nombres de la geocercas (POIs) de las que salió o a las que entró el vehículo
poiContact El contacto de la geocerca (si estuviera ingresado al sistema)
poiId Identificador de la geocerca (POI) donde sucedió el evento
startDate Nombre del evento detectado

Ejemplos:

{
  "date": 1528996543494,
  "distanceFromPoi": "157 km",
  "driver": "",
  "eventId": 512,
  "ignOnTime": 0,
  "lat": "15.280898",
  "lon": "-91.797898",
  "messageId": "isNotAt-dist",
  "metersFromPoi": 157041.0,
  "odometer": "0 km",
  "place": "CA-9 km62, Sanarate, El progreso, GT",
  "poiContact": "",
  "poiName": "RefPoint1",
  "ruleOwner": "Jose Perez",
  "ruleOwnerId": 1,
  "urId": 1024,
  "vehicle": "test vehicle 1 (PLATE1)"
}

{
  "date": 1529009273541,
  "eventId": 512,
  "ignOnTime": 0,
  "lat": "1.123",
  "lon": "1.123",
  "messageId": "enteredPoi",
  "odometer": 2001,
  "odometerUnits": "km",
  "place": "123 Sixth St, Austin, TX",
  "poiContact": "John Smith 713-232-3453",
  "poiGroupIds": [],
  "poiIds": [
    15432
  ],
  "poiNames": [
    "The office"
  ],
  "ruleOwner": "John Smith",
  "ruleOwnerId": 1,
  "urId": 2471,
  "vehicle": "test vehicle (PLATE)",
  "vehicle_tags": [
    "Vehicle Group/Tag 1"
  ]
}

WH: Ubicaciones (locations)

Startrack puede rebotar una copia de cada una de los eventos/ubicaciones que recibe de los dispositivos de rastreo.

Un administrador del sistema (-1) debe configurar el rebote para cada cliente que lo requiera.
Esto se hace en el menú Tech -> Rebote de datos

Por cada rebote se debe configurar la URL a donde se enviará el HTTP POST y el formato a usar. Existen dos formatos:

O: Location Data Object (Formato Json 1)

campo explicación
code Código identificador de evento (0=en movimiento, 1=paró, 2=ignición apagada, 3=ignición encendida, etc.)
vid Identificador del vehículo en Startrack
remote_id Identificador establecido por el usuario
license_plate Placa del vehículo
device_id Identificador del dispositivo de rastreo (imei)
ip Dirección ip desde donde se recibió el dato
port Puerto TCP/UDP desde donde se recibió el dato
lon Longitud en grados decimales
lat Latitud en grados decimales
valid_position Indicación si la posición es válida true/false
event_time Fecha del evento
system_time Fecha en que el evento fue procesado en el servidor
kmph Velocidad en kilómetros por hora
mph Velocidad en millas por hora
placename Descripción de la ubicación (nombre de calle, municipio, país)
poi_ids Identificadores de las geocercas (POI) dentro de las cuales sucedió el evento
poi_group_ids Identificadores de los grupos de geocercas (POI Group) dentro de los cuales sucedió el evento
alerts_count Número de alertas generadas por el evento
route_id Identificador de la ruta en curso
client_id Identificador del cliente
head Dirección magnetica
odometer Odómetro virtual (en km) al momento del evento
sys_odometer Contador de distancia recorrida (en km) interno del sistema -- no modificable por usuarios
hourmeter Horómetro virtual (en horas) al momento del evento
sys_hourmeter Contador de horas encendidas interno del sistema -- no modificable por usuarios
driver_id Identificador del conductor asignado actualmente
driver_ibutton Código del iButton del conductor asignado actualmente
ign_on Bool que indica si la ignición está encedida
veh_status Identificador del estado actual del vehículo
veh_description Descripción del vehículo
trip_dist Distancia del viaje en curso
direction_of_travel Dirección general en la que se dirige el vehículo en grados
poi Geocerca en la cual se encuentra el vehículo (en la definición de ese objeto se detalla los campos)

Ejemplo:

{
  "code": 0,
  "vid": 324,
  "remote_id": "mi correlativo",
  "license_plate": "P-123ABC",
  "device_id": 358741050302485,
  "ip": "216.58.192.100",
  "port": -1,
  "lon": "-85.54562",
  "lat": "10.67338",
  "valid_position": true,
  "event_time": "2016-09-08T17:42:14+0",
  "system_time": "2016-09-08T11:42:15.411-06:00",
  "kmph": 16,
  "mph": 10,
  "placename": "111 Oak Street, New York, NY 11010",
  "poi_ids": [
    1123,
    542
  ],
  "poi_group_ids": [
    203,
    203
  ],
  "alerts_count": 0,
  "route_id": null,
  "client_id": 0,
  "head": 359,
  "odometer": 1231.1,
  "sys_odometer": 100000.1,
  "hourmeter": 1000.1,
  "sys_hourmeter": 1.1,
  "driver_id": 123,
  "driver_ibutton": "ABC123",
  "ign_on": true,
  "veh_status": 0,
  "veh_description": "Camion GO4277",
  "trip_dist": 363.2599999999999,
  "direction_of_travel": 290,
  "poi": null
}

O: Location Data Object List (Formato Json 2)

campo explicación
code Código identificador de evento (0=en movimiento, 1=paró, 2=ignición apagada, 3=ignición encendida, etc.)
vid Identificador del vehículo
remote_id Identificador establecido por el usuario
license_plate Placa del vehículo
device_id Identificador del dispositivo de rastreo (imei)
ip Dirección ip desde donde se recibió el dato
lon Longitud en grados decimales
lat Latitud en grados decimales
event_time Fecha del evento
system_time Fecha en que el evento fue procesado en el servidor
mph Velocidad en millas por hora

Ejemplo:

[
  1,
  [
    {
      "code": 0,
      "vid": 324,
      "remote_id": "mi correlativo",
      "license_plate": "P-123ABC",
      "device_id": 358741050302485,
      "ip": "216.58.192.100",
      "lon": -8554562,
      "lat": 1067338,
      "event_time": "2016-09-08T16:31:44+0",
      "system_time": "2016-09-08T10:31:45.162-06:00",
      "mph": 9
    }
  ]
]