NAV
shell python javascript

Introducción

Bienvenid@ a la API Drivetech. Aquí se describe el protocolo de recepción de datos GPS provenientes de proveedores de GPS que requieran integrar sus vehículos a la Plataforma Drivetech inyectando eventos.

Para lograr un comportamiento cercano al tiempo real, la API Drivetech está preparada para recibir instantáneamente los eventos de cada vehículo, por lo que se espera recibir los datos con la misma frecuencia que los recibe el proveedor GPS.

La API Drivetech dispone de un mecanismo que le permite determinar cuándo un proveedor no ha inyectado eventos en un periodo de tiempo y así alertar al proveedor de lo ocurrido.

La API Drivetech utiliza el estilo de arquitectura REST para recibir la inyección de datos de proveedores externos autorizados, donde la información se recibe en formato JSON.

Autenticación

La API Drivetech utiliza el mecanismo de autenticación por token, donde se le asigna un Token a cada cliente y debe ser incorporado en la cabecera de cada petición. Si el Token no es válido o no está presente, entonces la petición retornará 401 Unauthorized. Cada cliente debe estar previamente registrado en la Plataforma Drivetech. Puedes solicitar tu Token de cliente en contacto@drivetech.pro.

Para autenticarse usa el siguiente código:

TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IkNvbnRyb2wgUG9zaXRpb24ifQ.ZYqC8s13jaUQiTvVPGIsg9sPEhsudB9iY-9jEBWpDgk'

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {TOKEN}'
}


# Debes pasar el header correcto en cada request.
curl "api_endpoint_here" \
  -H "Authorization: Bearer TOKEN"

const HOST = 'https://api.drivetech.pro'
const URL = '/provider/event/new/'
const TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IkNvbnRyb2wgUG9zaXRpb24ifQ.ZYqC8s13jaUQiTvVPGIsg9sPEhsudB9iY-9jEBWpDgk'

const postOptions = {
    hostname: HOST,
    path: URL,
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${TOKEN}`
    }
}

Asegúrate de reemplazar TOKEN por tu Token.

Drivetech espera recibir el Token en la cabezera de todas las peticiones, de la siguiente manera:

Authorization: Bearer TOKEN

Resiliencia

Es de extrema importancia que se envíen todos los eventos generados, ya que la Plataforma Drivetech reconstruye los recorridos de los vehículos a partir de estos datos. En vista de esto, se debe considerar que la API Drivetech puede tener eventuales mantenciones, con lo que las peticiones a la API no devolverán 200 OK. Se espera que los eventos que no fueron recibidos correctamente, ya sea por problemas del proveedor, que la API no estaba operativa o por problemas de formato, se reenvíen en peticiones posteriores hasta que se reciban correctamente. Para esto se dispone del parámetro buff con valor true, que le informa a la API Drivetech que el evento recibido es antiguo.

Inyección de Eventos

import requests

URL = 'https://api.drivetech.pro/provider/event/new/'
TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IkNvbnRyb2wgUG9zaXRpb24ifQ.ZYqC8s13jaUQiTvVPGIsg9sPEhsudB9iY-9jEBWpDgk'

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {TOKEN}'
}

data = {
    'plate': 'FVDH85',
    'buff': False,
    'datetime': '2019-06-15T05:51:09.671Z',
    'latitude': -33.361277,
    'longitude': -70.514483,
    'speed': 0,
    'azimuth': 45.27,
    'altitude': 853.32,
    'state': 'Idling',
    'event': {
        'type': 'GPS'
    },
    'ign_input': True,
    'doors': False,
    'gps_status': True,
    'odometer': 75340.6,
    'hourmeter': 356.33,
    'battery': 93.67,
    'power_supply': 24.076,
    'temperature1': 15.23,
    'temperature2': 7.74,
    'temperature3': -3.58,
    'fuel_percentage': 48.24,
    'mcc': 730,
    'mnc': 1,
    'lac': 13613,
    'cid': 86614082
}

r = requests.post(URL, json=data, headers=headers)
if r.status_code == 200:
    print('Requests succeed!')
elif r.status_code == 400:
    print('Bad request')
elif r.status_code == 401:
    print('Unauthorized')
elif r.status_code == 500:
    print('Internal Server Error')
else:
    print(f'{r.status_code} -> {r.json()}'

curl -X POST -k -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IkNvbnRyb2wgUG9zaXRpb24ifQ.ZYqC8s13jaUQiTvVPGIsg9sPEhsudB9iY-9jEBWpDgk' -i 'https://api.drivetech.pro/provider/event/new/' --data '{
    "plate": "FVDH85",
    "buff": false,
    "datetime": "2019-06-14T11:58:44.063406",
    "latitude": -33.361277,
    "longitude": -70.514483,
    "speed": 0,
    "azimuth": 45.27,
    "altitude": 853.32,
    "state": "Idling",
    "event": {
        "type": "GPS"
    },
    "ign_input": true,
    "doors": false,
    "gps_status": true,
    "odometer": 75340.6,
    "hourmeter": 356.33,
    "battery": 93.67,
    "power_supply": 24.076,
    "temperature1": 15.23,
    "temperature2": 7.74,
    "temperature3": -3.58,
    "fuel_percentage": 48.24,
    "mcc": 730,
    "mnc": 1,
    "lac": 13613,
    "cid": 86614082
}'

'use strict'

const http = require('http')

const HOST = 'https://api.drivetech.pro'
const URL = '/provider/event/new/'
const TOKEN = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6IkNvbnRyb2wgUG9zaXRpb24ifQ.ZYqC8s13jaUQiTvVPGIsg9sPEhsudB9iY-9jEBWpDgk'

const postOptions = {
    hostname: HOST,
    path: URL,
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${TOKEN}`
    }
}
const postData = {
    plate: 'FVDH85',
    buff: false,
    datetime: '2019-06-15T05:51:09.671Z',
    latitude: -33.340554,
    longitude: -70.509879,
    speed: 0,
    azimuth: 97.27,
    altitude: 853.32,
    state: 'Idling',
    event: {
        type: 'GPS'
    },
    ign_input: true,
    doors: false,
    gps_status: true,
    odometer: 75340.6,
    hourmeter: 325.5,
    battery: 93.67,
    power_supply: 24.076,
    temperature1: 15.23,
    temperature2: 7.74,
    temperature3: -3.58,
    fuel_percentage: 48.24,
    mcc: 730,
    mnc: 1,
    lac: 13613,
    cid: 86614082
}

const req = http.request(postOptions, res => {
    let response
    if (res.statusCode === 401) {
          console.log('Unauthorized')
    } else if (res.statusCode !== 200) {
          console.log(`Error ${res.statusCode}`)
    } else {
          res.setEncoding('utf8')
          let rawData = ''

          res.on('data', chunk => {
            rawData += chunk
          })

          res.on('end', () => {
            try {
                response = {
                    success: res.statusCode === 200,
                    code: res.statusCode,
                    response: rawData ? JSON.parse(rawData) : null
                }
                  console.log(response)
            } catch (err) {
                  console.log(`Error: ${err}`)
            }
          })
    }
})

req.on('error', err => console.log(`Error: ${err}`))
req.write(JSON.stringify(postData))
req.end()

El código de arriba devuelve un objeto JSON como este:

{
  "status": true,
  "description": "Successfully saved."
}

Actualmente la Plataforma Drivetech permite la inyección de los siguientes eventos:

  1. GPS (Posición GPS normal): Evento de reporte de posición geo-espacial periódico. Se espera recibir este evento al menos cada 1 minuto con el vehículo prendido y al menos cada una hora con el vehículo apagado. No hay restricciones de cantidad de eventos ni de periodicidad. Este es el reporte que permite hacer seguimiento en tiempo real de los vehículos y reconstruir su historial de recorrido.
  2. IGN (Ignición): Evento que reporta cuando un vehículo se prende o se apaga. Se espera recibir instantáneamente cuando ocurre el evento.
  3. SOS (Botón de pánico): Evento que reporta cuando se presiona el botón de pánico instalado en el vehículo (opcional).
  4. IDLING (Ralentí): Evento que reporta cuando un vehículo entra o sale de estado de ralentí.
  5. OVER_SPEED (Exceso de velocidad): Evento que reporta cuando un vehículo entra o sale de exceso de velocidad. La velocidad límite debe estar previamente configurada por el proveedor de GPS.
  6. LOW_BATTERY (Batería del dispositivo baja): Evento que reporta cuando la batería del dispositivo GPS está bajo un límite previamente configurado por el proveedor de GPS.
  7. DOOR (Puertas): Evento que reporta cuando se abre o cierra una puerta del vehículo.
  8. DRIVER_ID (Identificación de Conductor): Evento que reporta cuando un conductor se identifica mediante un sistema de identificación de conductor, que puede ser iButton, Rfid, u otros.
  9. GPS_SIGNAL (Señal GPS): Evento que reporta cuando el equipo pierde o recupera la señal GPS.
  10. HARSH_BEHAVIOR (Comportamiento Brusco): Evento que reporta cuando el vehículo genera un comportamiento Brusco. La especificación de cada comportamiento brusco depende del tipo de vehículo y de las definiciones de cada cliente.

Se debe realizar una petición por cada evento.

HTTP Request

POST https://api.drivetech.pro/provider/event/new/

Parámetros

Parámetro Tipo Requerido Descripción Ejemplo
plate string Sí Patente del vehículo sin espacios ni guiones. 'FVDH85'
buff bool Sí Indica si el dato es actual o antiguo. false por defecto. false
datetime string Sí Fecha Hora exacta del evento en UTC. '2019-06-12 23:33:12.000Z'
latitude float Sí Latitud del vehículo al generarse el evento. -33.361277
longitude float Sí Longitud del vehículo al generarse el evento. -70.514483
speed float Sí Velocidad del vehículo al generarse el evento. 25.60
azimuth float Sí Sentido de movimiento del vehículo al generarse el evento. 45.27
altitude float No Altitud del vehículo al generarse el evento (en msnm). 853.32
state string Sí Estado actual del vehículo. Opciones:
Tow: Remolcándose
Ignition Off Rest: Apagado estacionado
Idling: Ralentí,
Ignition On Moving: Prendido moviéndose		 'Ignition On Rest'
event Object Sí Tipo de envento. Revisar Tipos de Evento. { type: 'GPS' }
ign_input bool Sí Indica si el vehículo está prendido (true) o apagado (false). false por defecto. true
doors bool No Indica si las puertas están abiertas (true) o cerradas (false). false por defecto. false
gps_status bool No Indica si el equipo logró obtener su información GPS (true) o no (false). true por defecto. true
odometer float Sí Odómetro del vehículo al generarse el evento (en km). 75340.6
hourmeter float No Horómetro del vehículo al generarse el evento (en hrs). 356.32
battery float No Porcentaje de batería del dispositivo GPS al generarse el evento (en %). 93.67
power_supply float No Voltaje (en Voltios) de la fuente de poder al generarse el evento (en V). 24.076
temperature1 float No Valor del sensor de temperatura 1 en ºC. 15.23
temperature2 float No Valor del sensor de temperatura 2 en ºC. 7.74
temperature3 float No Valor del sensor de temperatura 3 en ºC. -3.58
fuel_percentage float No Porcentaje de combustible en el estanque del vehículo al generarse el evento (en %). 15.23
mcc int No Código móvil del país de la red a la cual el equipo está conectado. 730
mnc int No Código móvil de la red a la cual el equipo está conectado. 1
lac int No Código del área local de la red a la cual el equipo está conectado. 13613
cid int No ID de la celda a la cual el equipo está conectado. 86614082

Tipos de Evento (parámetro event)

type Parámetros extra Tipo Descripción Ejemplo
GPS - - Posición GPS del vehículo { type: 'GPS'}
IDLING status
duration		 bool
int		 Inicio ralentí (true), fuera de ralentí (false)
Duración del ralentí en segundos.		 { type: 'IDLING', status: false, duration: 155}
IGN status
duration		 bool
int		 Vehículo prendido (true), Apagado (false)
Tiempo del evento en segundos.		 { type: 'IGN', status: true, duration: 1354}
SOS - - Botón de pánico presionado { type: 'SOS'}
OVER_SPEED status bool Inicio exceso de velocidad (true)
Fin exceso de velocidad (false)		 { type: 'OVER_SPEED', status: true}
LOW_BATTERY - - Batería del dispositivo baja { type: 'LOW_BATTERY'}
DRIVER_ID driver_id string Identificador del conductor (iButton, RFID u otro) { type: 'DRIVER_ID', driver_id: '2354127698'}
DOOR status bool Puerta abierta (true)
Puerta cerada (false)		 { type: 'DOOR', status: true}
GPS_SIGNAL status bool Señal GPS recuperada (true)
Pérdida señal GPS (false)		 { type: 'GPS_SIGNAL', status: false}
HARSH_BEHAVIOR status
magnitude		 int
float		 Frenada brusca (0)
Aceleración brusca (1)
Giro brusco (2)		 { type: 'HARSH_BEHAVIOR', status: 0, magnitude: 4,2}

Errores

La API Drivetech puede devolver los siguientes errores:

// Bad request
{
  "status": false,
  "description": "Parameter plate is required"
}

// Unauthorized
{
  "status": false,
  "description": "Provider unauthorized"
}
Error Code Significado Ejemplo respuesta
400 Bad Request Request inválido.
401 Unauthorized No autorizado, token faltante o inválido.
404 Not Found La URL de consulta es incorrecta.
405 Method Not Allowed El método del request es distinto a POST.
500 Internal Server Error Error del servidor, intentar denuevo.
503 Service Unavailable Estamos temporalmente no disponible, intentar más tarde.
shell python javascript