Consultar todos los conductores

[ GET ]

Devuelve, de forma paginada, los conductores registrados para tu empresa. Permite ordenar los resultados por distintos criterios y filtrar por la fecha de alta. Este endpoint no genera cambios sobre los datos.

https://sync.airbagtech.io/driver

⚠️

Cambio de comportamiento: la respuesta ahora viene paginada

Una solicitud sin size ni limit devolvía antes todos los conductores de la empresa; ahora devuelve los primeros 50. Si tu integración asumía recibir la plantilla completa en una sola llamada, debe recorrer las páginas hasta que pagination.hasNext sea false.

Valores de datos

Campos válidos para el ordenamiento

Nombre	Descripción
fullName	Nombre completo del conductor.
lastName	Apellido del conductor.
civilStatus	Estado civil.
birhtdate	Fecha de nacimiento.
gender	Género.
hired	Fecha de contratación.
nationality	Nacionalidad.
created	Fecha de alta en la plataforma.
status	Estado de la cuenta (active / inactive).

Si no envías sort, los resultados se ordenan por identificador interno de forma ascendente. Ese orden es fijo y es lo que garantiza que dos páginas consecutivas no repitan ni se salten conductores.

⚠️

El valor `birhtdate` lleva una errata histórica

La fecha de nacimiento se ordena con el valor birhtdate (no birthdate). La errata forma parte del contrato vigente de la API: enviar birthdate devuelve el error Sort field not in the list.

🚫

`appStatus` ya no se admite como criterio de ordenamiento

Enviar sort=appStatus devuelve 400 con el mensaje Sort field not in the list. El valor que publica la API (Activo, Pendiente, Inactivo) se calcula a partir de dos campos almacenados, por lo que no puede resolverse en la base de datos: ordenar por él sólo alcanzaría a la página ya devuelta, no al total. Si necesitas ese orden, ordena del lado de tu integración tras recorrer las páginas.

Campos

Todos los campos son parámetros de consulta (query params) y son opcionales.

Nombre	Tipo	Requerido	Descripción
page	Number	No	Página a devolver, empezando en 1. Debe ser un entero positivo. Si no se envía, por defecto es 1.
size	Number	No	Número de conductores por página. Debe ser un entero entre 1 y 500. Si no se envía, por defecto es 50.
limit	Number	No	Alias de size, conservado por compatibilidad. Si envías ambos, prevalece size.
sort	String	No	Campo por el cual ordenar los resultados. Consulta la tabla de Campos válidos para el ordenamiento.
direction	String	No	Dirección del ordenamiento: asc (ascendente) o desc (descendente). Debe usarse junto con sort.
startDate	String	No	Fecha inicial del rango de alta a consultar. Debe usarse junto con endDate y ser anterior a esta. El filtro es exclusivo en el inicio: devuelve los registros con created posterior a este valor.
endDate	String	No	Fecha final del rango de alta a consultar. Debe usarse junto con startDate. El filtro es inclusivo en el fin: devuelve los registros con created menor o igual a este valor.

Restricciones al combinar parámetros

Si utilizas los parámetros startDate y endDate, el campo sort debe ser created o no especificarse. Ambas fechas viajan siempre en pareja: enviar sólo una devuelve error. El rango también acota el total, de modo que el número publicado corresponde a los conductores que realmente puedes recorrer.

Headers

Autorization
apikey {{API_KEY}}

Ejemplo

curl --location 'https://sync.airbagtech.io/driver' \
  --header 'Authorization: apikey {{API_KEY}}'

Ejemplo con paginación

curl --location 'https://sync.airbagtech.io/driver?page=2&size=50' \
  --header 'Authorization: apikey {{API_KEY}}'

Ejemplo con ordenamiento y rango de fechas

curl --location 'https://sync.airbagtech.io/driver?startDate=2024-01-01&endDate=2024-12-31&sort=created&direction=desc&size=25' \
  --header 'Authorization: apikey {{API_KEY}}'

Respuestas

✅ Respuesta exitosa (200 OK)

Devuelve el arreglo drivers con la página solicitada, cuántos conductores trae esa página (length), cuántos coinciden con la consulta completa (total) y los metadatos de paginación. Cada elemento de drivers tiene la misma estructura que la respuesta de Consultar la info de un conductor, incluidos los bloques de gamificación currentLevel y currentStreak.

{
  "status": true,
  "length": 2,
  "drivers": [
    {
      "id": "EMP-1042",
      "airbagId": "ab12cd34ef56gh78ij90kl12mn34op56",
      "company": "Transportes Ejemplo",
      "name": "Juan",
      "lastName": "Pérez Ramírez",
      "fullName": "Juan Pérez Ramírez",
      "email": "[email protected]",
      "phone": "+525598765432",
      "gender": "male",
      "birthdate": "1992-08-14T06:00:00.000Z",
      "civilStatus": "single",
      "nationality": "mex",
      "hired": "2021-03-01T06:00:00.000Z",
      "created": "2022-05-18T15:42:00.000Z",
      "status": "active",
      "appStatus": "Activo",
      "groups": ["grp_A1b2C3d4E5f6G7h8I9j0"],
      "coins": 312,
      "useAirbagTelematics": true,
      "emergencyContact": {
        "phone": "+525512345678",
        "name": "Contacto Ejemplo",
        "type": "cellphone"
      }
    },
    {
      "id": "EMP-1043",
      "airbagId": "cd34ef56gh78ij90kl12mn34op56ab12",
      "company": "Transportes Ejemplo",
      "name": "María",
      "lastName": "López Hernández",
      "fullName": "María López Hernández",
      "phone": "+525511223344",
      "created": "2024-02-02T09:15:00.000Z",
      "status": "active",
      "appStatus": "Pendiente",
      "coins": 0,
      "useAirbagTelematics": false,
      "emergencyContact": {
        "phone": "+525599887766",
        "name": "Contacto Ejemplo 2",
        "type": "landphone"
      }
    }
  ],
  "total": 320,
  "pagination": {
    "currentPage": 1,
    "size": 50,
    "totalPages": 7,
    "hasNext": true
  }
}

nota

En una respuesta real, drivers contiene length elementos y cada ficha incluye todos los campos disponibles del conductor. El ejemplo anterior muestra sólo dos registros y omite los campos no informados para ilustrar los distintos escenarios: un conductor con la ficha completa y otro recién dado de alta que aún no ha iniciado sesión.

Descripción de campos de respuesta

Campo	Tipo	Descripción
status	Boolean	Indica si la operación fue exitosa.
length	Number	Cuántos conductores trae esta página. Siempre coincide con el número de elementos de drivers y es menor que size en la última página.
drivers	Array<Object>	Conductores de la página solicitada. Ver tabla abajo.
total	Number	Cuántos conductores coinciden con la consulta en total, sumando todas las páginas. Si filtras por fechas, el total respeta ese rango.
pagination	Object	Metadatos de paginación. Ver tabla abajo.

ℹ️

`length` y `total` no son el mismo número

length es el tamaño de la página que acabas de recibir; total es el tamaño del conjunto completo. Para saber cuántos conductores tiene tu empresa usa total, no length.

Campos dentro de pagination

Campo	Tipo	Descripción
currentPage	Number	Página devuelta.
size	Number	Tamaño de página aplicado. Es el que resolvió el servidor, que no siempre es el que pidió la solicitud: sin size ni limit vale 50.
totalPages	Number	Número total de páginas disponibles para el size aplicado.
hasNext	Boolean	true si existe una página posterior. Recorre la lista hasta que valga false.

Campos destacados dentro de cada elemento de drivers

La ficha completa se describe en Consultar la info de un conductor. Estos son los campos que conviene tener presentes al recorrer la lista:

Campo	Tipo	Descripción
id	String	Identificador del conductor proporcionado por tu empresa al crearlo. Es el ID que utilizas en tus sistemas y el que se envía en la ruta del resto de endpoints de conductores.
airbagId	String	Identificador interno único del conductor en la plataforma Airbag. Útil para referencias cruzadas.
company	String	Nombre de la organización a la que pertenece el conductor.
status	String	Estado de la cuenta. Valores: active o inactive.
appStatus	String	Estado de la aplicación móvil del conductor. Valores: Activo, Pendiente o Inactivo. Se calcula al momento de la consulta, por lo que no puede usarse para ordenar.
useAirbagTelematics	Boolean	Indica si la telemetría se captura con el sistema de Airbag. Es false cuando la empresa envía sus propios datos mediante los endpoints de Eventos.
created	String	Fecha de alta en la plataforma, en formato ISO 8601. Es el campo sobre el que actúan startDate y endDate.

⚠️ Sin resultados (404 Not Found)

Cuando ningún conductor coincide con los parámetros enviados, la API responde 404 conservando status: true, ya que no se trata de un error de la solicitud sino de una búsqueda sin coincidencias. También ocurre al pedir una página posterior a la última.

{
  "status": true,
  "message": "No driver found with given parameters",
  "length": 0,
  "drivers": [],
  "total": 0,
  "pagination": {
    "currentPage": 1,
    "size": 50,
    "totalPages": 0,
    "hasNext": false
  }
}

⚠️

Trata el 404 como lista vacía

Si tu integración considera cualquier 404 como un fallo, una empresa sin conductores o un rango de fechas sin altas romperá la sincronización. Evalúa el campo status antes que el código HTTP.

❌ Parámetros inválidos (400 Bad Request)

Se devuelve cuando algún parámetro de consulta no cumple las reglas descritas arriba. Si hay varios errores, los mensajes se concatenan separados por coma.

{
  "status": false,
  "message": "size must be an integer between 1 and 500"
}

Mensaje	Causa
page must be a positive integer	page no es un entero o es menor que 1.
size must be an integer between 1 and 500	size (o limit) no es un entero o queda fuera del rango permitido.
StartDate && EndDate pair must be present.	Se envió sólo una de las dos fechas.
startDate must be before endDate	El rango está invertido.
startDate or endDate not valid	Alguna fecha no tiene un formato interpretable.
If start or endDate present then sort must be created or do not pass anything.	Se combinó un rango de fechas con un sort distinto de created.
Direction must be 'asc' or 'desc' but {valor} was found	direction tiene un valor no permitido.
Limit must be of type number but a {tipo} was found	limit no es numérico.
Sort field not in the list	sort no está entre los campos válidos. Es el error que devuelve sort=appStatus.

❌ Respuesta con error (401 Unauthorized)

Se devuelve cuando la API key es inválida o no fue enviada.

{
  "status": false,
  "message": "Error: Invalid or missing API key",
  "errorId": "sentry_error_id_123"
}

Recomendaciones

Para recorrer la plantilla completa, incrementa page mientras pagination.hasNext sea true en lugar de asumir un número fijo de páginas. Para sincronizaciones incrementales, filtra por startDate y endDate sobre la fecha de alta en lugar de descargar toda la plantilla en cada ciclo. El tamaño máximo por página es 500: pedir menos páginas grandes es más eficiente que muchas pequeñas, pero ten en cuenta el peso de cada ficha.