Consultar la info de ranking

[ POST ]

Consulta el ranking de todos los conductores de tu empresa según una métrica específica. El endpoint es de sólo lectura y no genera cambios sobre los datos.

https://sync.airbagtech.io/ranking

Tipos de ranking

Existen dos modos de consulta, controlados por el campo type. Cada modo requiere un formato distinto en targetDate:

type	Periodo que representa	Formato de `targetDate`	Ejemplo
`accumulated`	Mes en curso: desde el primer día del mes hasta la fecha indicada.	`YYYY-MM-DD`	`2025-02-15`
`consolidated`	Mes completo ya finalizado (consolidación mensual).	`YYYY-MM`	`2025-01`

¿Cuál debo usar?

Usa accumulated cuando necesites una foto del progreso del mes corriente. La fecha debe incluir día (YYYY-MM-DD) porque el cálculo se hace del día 1 del mes hasta ese día.
Usa consolidated para obtener el ranking final de un mes que ya terminó. La fecha sólo lleva año y mes (YYYY-MM) porque representa el mes completo; no se envía día.

Métricas disponibles

El campo feature indica qué métrica se utiliza para ordenar a los conductores:

Valor	Métrica	Descripción
`1`	Acceleration	Aceleraciones agresivas detectadas.
`2`	Braking	Frenadas agresivas detectadas.
`3`	PhoneUsage	Uso del celular mientras el conductor está en movimiento.
`4`	Speeding	Excesos de velocidad respecto al límite permitido.
`5`	Cornering	Curvas tomadas de forma agresiva.
`6`	Overall	Puntaje global combinando todas las métricas de conducción.
`7`	Distance	Distancia total recorrida durante el periodo.
`8`	Coins	Monedas acumuladas en el sistema de gamificación.

Campos

Nombre	Tipo	Requerido	Descripción
`feature`	Number	Sí	Métrica por la que se ordenará el ranking. Consulta la tabla de Métricas disponibles (valores del `1` al `8`).
`type`	String	Sí	Tipo de ranking. Valores soportados: `accumulated` (mes en curso) o `consolidated` (mes ya finalizado). Ver Tipos de ranking.
`targetDate`	String	Sí	Fecha de referencia. El formato depende de `type`: `YYYY-MM-DD` para `accumulated` y `YYYY-MM` para `consolidated`.

Headers

Content-Type	Autorization
application/json	apikey `{{API_KEY}}`

Body

{
  "feature": 6,
  "type": "accumulated",
  "targetDate": "2025-02-15"
}

Ejemplos

Ranking acumulado del mes en curso

Obtén el puntaje global (feature: 6) desde el 1 de febrero de 2025 hasta el día 15:

curl --location 'https://sync.airbagtech.io/ranking' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: apikey {{API_KEY}}' \
  --data '{
    "feature": 6,
    "type": "accumulated",
    "targetDate": "2025-02-15"
  }'

Ranking consolidado de un mes completo

Obtén el ranking final de distancia recorrida (feature: 7) de enero de 2025:

curl --location 'https://sync.airbagtech.io/ranking' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: apikey {{API_KEY}}' \
  --data '{
    "feature": 7,
    "type": "consolidated",
    "targetDate": "2025-01"
  }'

Respuestas

✅ Respuesta exitosa (200 OK)

Devuelve un arreglo ranking con todos los conductores de la empresa, ordenados por la posición (Place) que ocupan según la métrica seleccionada en feature. Cada entrada incluye estadísticas agregadas del periodo.

{
  "status": true,
  "ranking": [
    {
      "Distance": 354,
      "Duration": 557,
      "Place": 1,
      "Trips": 36,
      "Value": 93,
      "fullName": "Juan Pérez Ramírez",
      "userId": "EMP-1042",
      "_id": "63a1b2c3d4e5f6789012ab01"
    },
    {
      "Distance": 29,
      "Duration": 94,
      "Place": 2,
      "Trips": 2,
      "Value": 92,
      "fullName": "Laura Méndez",
      "userId": "Kp9qLmRsT2uVwXyZaBcD",
      "_id": "63a1b2c3d4e5f6789012ab02"
    },
    {
      "Distance": 163,
      "Duration": 194,
      "Place": 3,
      "Trips": 14,
      "Value": 86,
      "fullName": "Abdel Quiñonez Jaime",
      "userId": "Np7QrSt8UvWxYz0AbCdE",
      "_id": "63a1b2c3d4e5f6789012ab03"
    },
    {
      "Distance": 407,
      "Duration": 615,
      "Place": 4,
      "Trips": 30,
      "Value": 84,
      "fullName": "Roberto Sánchez",
      "userId": "Lm8NpQrSt2UvWxYzAbCd",
      "_id": "63a1b2c3d4e5f6789012ab04"
    },
    {
      "Distance": 286,
      "Duration": 608,
      "Place": 5,
      "Trips": 24,
      "Value": 79,
      "fullName": "Javier Ortega",
      "userId": "Qr3StUv4WxYz5aBcDeFg",
      "_id": "63a1b2c3d4e5f6789012ab05"
    },
    {
      "Distance": 70,
      "Duration": 229,
      "Place": 8,
      "Trips": 12,
      "Value": 61,
      "fullName": "Pamela Ruiz",
      "userId": "Bc7DeFgH8iJkLmNoPqRs",
      "_id": "63a1b2c3d4e5f6789012ab08"
    },
    {
      "Distance": 0,
      "Duration": 0,
      "Place": 11,
      "Trips": 0,
      "Value": 0,
      "fullName": "Ana Martínez",
      "userId": "Tv4WxYz5AbCd6EfGhIjK",
      "_id": "63a1b2c3d4e5f6789012ab0b"
    }
    // … (resto de conductores hasta completar la lista)
  ]
}

nota

La lista incluye a todos los conductores de la empresa, incluso a quienes no hicieron viajes durante el periodo (aparecen con Distance, Duration, Trips y Value en 0 al final del ranking).
El significado de Value depende del feature enviado. Por ejemplo, con feature: 6 (Overall) es un puntaje de 0 a 100; con feature: 7 (Distance) son kilómetros recorridos; con feature: 8 (Coins) son monedas acumuladas.
Place es la posición 1-indexada del conductor dentro del ranking. Los empates se resuelven internamente con criterios secundarios como Trips o Distance.

Descripción de campos de respuesta

Campo	Tipo	Descripción
`status`	Boolean	Indica si la operación fue exitosa.
`ranking`	Array<Object>	Lista de conductores ordenados por la métrica seleccionada. Ver tabla abajo.

Campos dentro de cada elemento de `ranking`

Campo	Tipo	Descripción
`userId`	String	ID del conductor proporcionado por la empresa al crearlo. Es el ID que utilizas en tus sistemas.
`_id`	String	Identificador interno del registro de ranking en la base de datos de Airbag. Útil para trazabilidad pero no se utiliza como referencia cruzada con otros endpoints.
`fullName`	String	Nombre completo del conductor al momento de calcular el ranking.
`Place`	Number	Posición del conductor dentro del ranking (1-indexada). `1` representa la mejor posición.
`Value`	Number	Puntaje del conductor para la métrica seleccionada en `feature`. Sus unidades dependen de `feature`: puntos (0–100) para `Acceleration`, `Braking`, `PhoneUsage`, `Speeding`, `Cornering` y `Overall`; kilómetros para `Distance`; monedas para `Coins`.
`Distance`	Number	Distancia total recorrida por el conductor durante el periodo, en kilómetros.
`Duration`	Number	Tiempo total manejado por el conductor durante el periodo, en minutos.
`Trips`	Number	Número total de viajes completados por el conductor durante el periodo.

❌ Respuesta con error (400 Bad Request)

Se devuelve cuando los campos son inválidos (por ejemplo, feature fuera del rango 1–8, type distinto a accumulated/consolidated, o un targetDate que no respeta el formato esperado para el type indicado).

{
  "status": false,
  "message": "Error: targetDate must match YYYY-MM when type is 'consolidated'",
  "errorId": "sentry_error_id_123"
}

Tipos de ranking​

Métricas disponibles​

Campos​

Headers​

Body​

Ejemplos​

Ranking acumulado del mes en curso​

Ranking consolidado de un mes completo​

Respuestas​

✅ Respuesta exitosa (200 OK)​

Descripción de campos de respuesta​

Campos dentro de cada elemento de ranking​

❌ Respuesta con error (400 Bad Request)​