Consultar eventos de un conductor

🔒

Sólo datos de telemetría externa

Este endpoint devuelve los eventos que llegan a Airbag desde una telemetría externa: los que carga Airbag desde Samsara o Motive, o los que tu empresa envía con el POST. No incluye los eventos que registra la app de Airbag; revisa ¿De dónde salen estos datos? para saber dónde consultarlos.

[ GET ]

Consulta los eventos de seguridad registrados para un conductor específico o para todos los conductores de la compañía en un día determinado o en un rango de fechas. Cada registro resume un día de un conductor: eventos, distancia, duración y puntaje. Es útil para análisis histórico, reportes de seguridad vial y para evaluar el desempeño de los conductores a lo largo del tiempo.

# Consulta para un día específico
https://sync.airbagtech.io/provider-data?driverId={{DRIVER_ID}}&date={{DATE}}

# Consulta para un rango de fechas
https://sync.airbagtech.io/provider-data?driverId={{DRIVER_ID}}&startDate={{START_DATE}}&endDate={{END_DATE}}

# Consulta con paginación
https://sync.airbagtech.io/provider-data?driverId={{DRIVER_ID}}&startDate={{START_DATE}}&endDate={{END_DATE}}&limit=100&page=2

¿De dónde salen estos datos?

Lo que devuelve este endpoint depende del proveedor de telemetría de tu empresa:

Proveedor de la empresa	Origen de los datos
Samsara o Motive	Airbag los carga automáticamente con un proceso diario.
custom (telemetría propia)	Los envía tu empresa con Crear o actualizar información del día.
Sin proveedor externo (telemetría de la app Airbag)	Este endpoint siempre devuelve data: []. Los eventos están por viaje en Logs de viaje (POST /trips/logs/:tripId) y resumidos por día en Resumen diario de viajes (GET /trips/daily-summary).

Campos

Todos los parámetros se envían como query parameters y son opcionales.

Nombre	Tipo	Requerido	Descripción
driverId	String	No	ID del conductor. Acepta el ID que tu empresa usó al crear el conductor o el airbagId. Si se omite, se devuelven los registros de todos los conductores de la compañía.
date	String	No	Fecha específica del registro en formato YYYY-MM-DD. Ejemplo: "2025-10-19".
startDate	String	No	Fecha inicial del rango en formato YYYY-MM-DD. Debe usarse junto con endDate.
endDate	String	No	Fecha final del rango en formato YYYY-MM-DD. Debe usarse junto con startDate.
limit	Number	No	Registros por página. Entero entre 1 y 1000. Por defecto 50.
page	Number	No	Número de página. Entero mayor o igual a 1. Por defecto 1.

Headers

Authorization
apikey {{API_KEY}}

Ejemplos

Consulta para un día específico

curl --location 'https://sync.airbagtech.io/provider-data?driverId=1234&date=2023-10-01' \
--header 'Authorization: apikey {{API_KEY}}'

Consulta para un rango de fechas

curl --location 'https://sync.airbagtech.io/provider-data?driverId=1234&startDate=2023-10-01&endDate=2023-10-03' \
--header 'Authorization: apikey {{API_KEY}}'

Consulta con paginación

curl --location 'https://sync.airbagtech.io/provider-data?startDate=2023-10-01&endDate=2023-10-31&limit=100&page=2' \
--header 'Authorization: apikey {{API_KEY}}'

Respuesta exitosa

{
  "status": true,
  "data": [
    {
      "driverId": "1234",
      "distance": 150.5,
      "duration": 10.5,
      "score": 85.2,
      "date": "2023-10-01",
      "securityEvents": [
        {
          "event": "speeding",
          "count": 2
        }
      ]
    },
    {
      "driverId": "5678",
      "distance": 200.0,
      "duration": 5,
      "score": null,
      "date": "2023-10-01",
      "securityEvents": []
    }
  ],
  "pagination": {
    "total": 32,
    "totalPages": 16,
    "currentPage": 1,
    "hasNext": true,
    "remainingItems": 30
  }
}

Campos de la respuesta

Nombre	Tipo	Descripción
status	Boolean	true si la consulta se procesó correctamente.
data	Array	Registros encontrados, uno por conductor y día. Vacío si no hay datos.
data[].driverId	String	ID del conductor que tu empresa usó al crearlo (o el airbagId si no tiene uno), aunque la consulta se haya hecho con el airbagId.
data[].distance	Number	Distancia recorrida en el día, en kilómetros.
data[].duration	Number	Tiempo de conducción del día, en horas.
data[].score	Number | null	Puntaje de seguridad del día. Es null cuando el registro se envió sin puntaje.
data[].date	String	Fecha del registro (YYYY-MM-DD).
data[].securityEvents	Array	Eventos del día con su cantidad ({event, count}). Puede venir vacío ([]) si el conductor no tuvo eventos ese día.
pagination.total	Number	Total de registros que cumplen los filtros.
pagination.totalPages	Number	Total de páginas con el limit usado.
pagination.currentPage	Number	Página devuelta.
pagination.hasNext	Boolean	true si hay más páginas después de la actual.
pagination.remainingItems	Number	Registros que quedan después de la página actual.

ℹ️

Tipos de eventos

Los valores del campo event dentro de securityEvents corresponden a las llaves listadas en la documentación de Eventos. En empresas con Samsara o Motive también pueden aparecer fuel_efficiency e idling_percentage, que carga Airbag.

Respuesta sin datos

{
  "status": true,
  "data": [],
  "pagination": {
    "total": 0,
    "totalPages": 0,
    "currentPage": 1,
    "hasNext": false,
    "remainingItems": 0
  }
}

Respuestas con error

400 — Parámetros inválidos

Se devuelve cuando una fecha no tiene el formato YYYY-MM-DD, cuando falta una de las dos fechas del rango o cuando limit o page están fuera de rango. message indica el parámetro y el motivo.

{
  "error": "VALIDATION_FAILED",
  "message": "endDate: endDate is required when startDate is provided.",
  "details": []
}

401 — No autorizado

{
  "status": false,
  "error": "You are not authorized to perform this action",
  "errorId": "-1"
}

500 — Error interno

{
  "status": false,
  "message": "Error: Request cannot be processed.",
  "errorId": "a1b2c3d4e5f6"
}

Notas importantes

• Todos los parámetros son opcionales, permitiendo consultas flexibles.
• Si no se especifica driverId, se devolverán datos de todos los conductores de la compañía.
• Si se usa startDate, debe incluirse también endDate, y viceversa.
• La paginación está incluida en todas las respuestas exitosas.
• La respuesta siempre devuelve un array en data, incluso para consultas de un solo día.