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. targetDate indica el mes a consultar: se acepta cualquier fecha válida de ese mes, y estos son los formatos recomendados:

type	Periodo que representa	Formato recomendado 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. targetDate debe caer en el mes actual; si no, la solicitud se rechaza.
• Usa consolidated para obtener el ranking final de un mes que ya terminó. targetDate debe caer en un mes pasado; si es del mes actual, la solicitud se rechaza.

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 del mes a consultar. Debe caer en el mes actual para accumulated y en un mes pasado para consolidated. Ver Tipos de ranking.

Headers

Content-Type	Authorization
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"
    },
    {
      "Distance": 29,
      "Duration": 94,
      "Place": 2,
      "Trips": 2,
      "Value": 92,
      "fullName": "Laura Méndez",
      "userId": "Kp9qLmRsT2uVwXyZaBcD"
    },
    {
      "Distance": 163,
      "Duration": 194,
      "Place": 3,
      "Trips": 14,
      "Value": 86,
      "fullName": "Abdel Quiñonez Jaime",
      "userId": "Np7QrSt8UvWxYz0AbCdE"
    },
    {
      "Distance": 407,
      "Duration": 615,
      "Place": 4,
      "Trips": 30,
      "Value": 84,
      "fullName": "Roberto Sánchez",
      "userId": "Lm8NpQrSt2UvWxYzAbCd"
    },
    {
      "Distance": 286,
      "Duration": 608,
      "Place": 5,
      "Trips": 24,
      "Value": 79,
      "fullName": "Javier Ortega",
      "userId": "Qr3StUv4WxYz5aBcDeFg"
    },
    {
      "Distance": 70,
      "Duration": 229,
      "Place": 8,
      "Trips": 12,
      "Value": 61,
      "fullName": "Pamela Ruiz",
      "userId": "Bc7DeFgH8iJkLmNoPqRs"
    },
    {
      "Distance": 0,
      "Duration": 0,
      "Place": 11,
      "Trips": 0,
      "Value": 0,
      "fullName": "Ana Martínez",
      "userId": "Tv4WxYz5AbCd6EfGhIjK"
    }
  ]
}

Ejemplo abreviado: la respuesta real continúa con el 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.
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)

{
  "status": false,
  "message": "Error: Accumulated ranking can only be called when target date is same as current month",
  "errorId": "sentry_error_id_123"
}

Mensaje	Causa
Error: Feature is required	Falta feature.
Error: Type is required	Falta type.
Error: Unkown type: <type>	type no es accumulated ni consolidated.
Error: Accumulated ranking can only be called when target date is same as current month	type es accumulated y targetDate no cae en el mes actual.
Error: Consolidated ranking can only be called when target date is from a past month	type es consolidated y targetDate cae en el mes actual.
Error: Unable to retrieve ranking for given parameters	No hay ranking para ese periodo todavía, feature está fuera del rango 1–8 o targetDate no es una fecha válida.
Error: Driver not found	Uno de los conductores del ranking ya no existe; por ahora esto impide devolver el ranking completo (se está corrigiendo).