Consultar la info de un conductor

[ GET ]

Consulta la información de un conductor sin alterar los valores del mismo.

https://sync.airbagtech.io/driver/{{DRIVER_ID}}

Campos

Nombre	Tipo	Requerido	Descripción
DRIVER_ID	String	Si	ID del conductor al que se le va a cambiar el estado.

Headers

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

Ejemplo

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

Respuestas

✅ Respuesta exitosa (200 OK)

Devuelve la ficha completa del conductor junto con su progreso de gamificación (nivel, racha), los indicadores de su primer acceso a la app móvil y los metadatos de la cuenta.

{
  "status": true,
  "driver": {
    "appStatus": "Activo",
    "birthdate": "1992-08-14T06:00:00.000Z",
    "civilStatus": "single",
    "coins": 312,
    "company": "Transportes Ejemplo",
    "created": "2022-05-18T15:42:00.000Z",
    "currentLevel": {
      "currentDistance": 1823.4512038172645,
      "remainingDistance": 3176.5487961827355,
      "to": 10000,
      "levelId": "a1B2c3D4e5F6g7H8i9J0",
      "maxLevel": 7,
      "name": "Nivel 4",
      "from": 5001,
      "percentageCompleted": 36,
      "totalDistanceTravelled": 6823.451203817265,
      "targetDistance": 5000
    },
    "currentStreak": {
      "isInStreak": true,
      "lastDayWithTrips": "2025-03-10T00:00:00.000Z",
      "maxHistoricalStreak": 9,
      "totalDaysOfStreak": 3,
      "lastWeekDaysStreak": [
        {
          "date": "2025-03-10T00:00:00.000Z",
          "dayCharacter": "L",
          "dayOfWeek": "monday",
          "streak": "IN_STREAK_ACTIVE"
        },
        {
          "date": "2025-03-09T00:00:00.000Z",
          "dayCharacter": "D",
          "dayOfWeek": "sunday",
          "streak": "IN_STREAK_ACTIVE"
        },
        {
          "date": "2025-03-08T00:00:00.000Z",
          "dayCharacter": "S",
          "dayOfWeek": "saturday",
          "streak": "IN_STREAK_INACTIVE"
        },
        {
          "date": "2025-03-02T00:00:00.000Z",
          "dayCharacter": "D",
          "dayOfWeek": "sunday",
          "streak": "OUT_OF_STREAK"
        }
      ]
    },
    "email": "[email protected]",
    "emailIsVerified": true,
    "emailVerified": true,
    "emergencyContact": {
      "phone": "+525512345678",
      "name": "Contacto Ejemplo",
      "type": "cellphone"
    },
    "firstLogin": false,
    "firstLoginDate": "2022-05-19T14:03:27.000Z",
    "fullName": "Juan Pérez Ramírez",
    "gender": "male",
    "groups": ["grp_A1b2C3d4E5f6G7h8I9j0"],
    "growthStatus": "ok",
    "hasActiveSchedule": true,
    "hasClaimedFirstTripBonus": true,
    "hasClaimedWelcomeBonus": true,
    "hasMadeFirstTrip": true,
    "hasMarketingNotifications": false,
    "hired": "2021-03-01T06:00:00.000Z",
    "isDriving": false,
    "isResting": false,
    "lastName": "Pérez Ramírez",
    "license": {
      "number": "A1234567",
      "type": "federal",
      "expiration": "2027-11-30T00:00:00.000Z"
    },
    "mobileOs": "android",
    "name": "Juan",
    "nationalId": "PERJ920814HDFRMN03",
    "nationality": "mex",
    "phone": "+525598765432",
    "startStage": "0",
    "status": "active",
    "redeemCount": 2,
    "airbagId": "ab12cd34ef56gh78ij90kl12mn34op56",
    "id": "EMP-1042",
    "useAirbagTelematics": true
  }
}

ℹ️

Los campos sin valor se omiten, no llegan como null

La ficha se arma con los datos que el conductor tiene almacenados. Un campo que nunca fue informado no viaja en el JSON: la clave simplemente no aparece, en lugar de llegar como null o como cadena vacía. Comprueba que la clave exista antes de leerla y no asumas que todos los conductores traen el mismo conjunto de campos. La columna Presencia de las tablas siguientes indica cuáles puedes esperar siempre.

Descripción de campos de respuesta

Campo	Tipo	Descripción
status	Boolean	Indica si la operación fue exitosa.
driver	Object	Objeto con los datos completos del conductor.

Campos dentro de driver

La ficha se agrupa en tres bloques para facilitar su lectura: identificación y datos personales, estado de la cuenta y de la app, y gamificación. Los tres pertenecen al mismo objeto driver, sin anidamiento adicional.

Identificación y datos personales

Campo	Tipo	Presencia	Descripción
id	String	Casi siempre	Identificador único del conductor proporcionado al crearlo. Es el ID que utilizas en tus sistemas y el que viaja en la ruta del resto de endpoints de conductores. Falta únicamente en registros heredados que nunca recibieron un identificador interno.
airbagId	String	Siempre	Identificador interno único en la plataforma Airbag. Útil para referencias cruzadas.
company	String	Siempre	Nombre de la organización a la que pertenece el conductor.
name	String	Siempre	Nombre de pila del conductor, normalizado a mayúsculas y sin acentos.
lastName	String	Siempre	Apellido del conductor, normalizado a mayúsculas y sin acentos.
fullName	String	Siempre	Nombre completo (name + lastName).
email	String	Opcional	Correo electrónico del conductor.
emailVerified	Boolean	Siempre	Indica si el correo ha sido verificado. Es el campo canónico.
emailIsVerified	Boolean	Opcional	Alias legado de emailVerified. Se mantiene por compatibilidad; usa emailVerified en integraciones nuevas.
phone	String	Opcional	Teléfono con código de país (formato +525555555555).
gender	String	Opcional	Género del conductor. Valores: male, female, other.
birthdate	String	Opcional	Fecha de nacimiento en formato ISO 8601. Al crear o editar se informa como birthDate.
civilStatus	String	Opcional	Estado civil. Valores: single, consensual-union, married, divorced, widowed.
nationalId	String	Opcional	Identificación nacional (CURP, DNI, etc.). Es de sólo lectura: no puede establecerse desde los endpoints de crear o editar conductor.
nationality	String	Opcional	Código ISO 3166-1 de tres letras (por ejemplo mex). Es la nacionalidad de la persona, no el país donde opera: para eso está country.
country	String	Opcional	País de operación del conductor. Determina cómo la plataforma normaliza los teléfonos: mex, col y per tienen tratamiento específico de prefijo y longitud. Úsalo, y no nationality, si necesitas validar o formatear phone y emergencyContact.phone en flotas multipaís.
hired	String	Opcional	Fecha de contratación en formato ISO 8601. Al crear o editar se informa como companyStartDate.
groups	Array<String>	Opcional	IDs de los grupos a los que pertenece el conductor. Ausente cuando no tiene grupo asignado.
license	Object	Opcional	Licencia de conducir registrada por el conductor desde la app móvil. Ver Campos dentro de license. Es de sólo lectura: no puede establecerse ni modificarse desde esta API.

Estado de la cuenta y de la app

Campo	Tipo	Presencia	Descripción
created	String	Siempre	Fecha de alta en la plataforma, en formato ISO 8601.
status	String	Siempre	Estado de la cuenta. Valores: active o inactive.
appStatus	String	Siempre	Estado de la aplicación móvil del conductor. Valores: Activo, Pendiente, Inactivo. Se calcula al momento de la consulta, por lo que no puede usarse para ordenar el listado.
growthStatus	String	Opcional	Clasificación del desempeño y la actividad del conductor. Valores: new, star, meteor, ok, attention, risk, reactivable, reactivated, hbRecoverable, hbPotential, hbInactive, lost1, lost2, inactive, rest, unknown.
startStage	String	Siempre	Etapa del flujo de onboarding en la que se encuentra el conductor.
firstLogin	Boolean	Siempre	true si el conductor aún no ha iniciado sesión por primera vez en la app móvil.
firstLoginDate	String	Opcional	Fecha y hora del primer inicio de sesión en la app móvil, en formato ISO 8601 (UTC). Está ausente mientras el conductor no haya iniciado sesión, y también en registros heredados que ya lo habían hecho antes de que este campo existiera. Para saber si un conductor llegó a usar la app, evalúa firstLogin === false en lugar de la presencia de esta fecha. Ejemplo: 2022-05-19T14:03:27.000Z
mobileOs	String	Opcional	Sistema operativo del dispositivo desde el que el conductor usa la app móvil. Valores: android, apple. Se registra durante el inicio de sesión y se actualiza si el conductor cambia de dispositivo, por lo que está ausente mientras no haya iniciado sesión al menos una vez.
isDriving	Boolean	Siempre	Indica si el conductor está conduciendo en este momento.
isResting	Boolean	Siempre	Indica si el conductor se encuentra en periodo de descanso.
hasActiveSchedule	Boolean	Siempre	Indica si tiene una jornada laboral activa configurada.
hasMarketingNotifications	Boolean	Opcional	Preferencia de notificaciones de marketing.
useAirbagTelematics	Boolean	Siempre	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.
providerStartDate	String	Opcional	Fecha, en formato ISO 8601, desde la que el conductor opera con un proveedor de telemetría externo. Guarda relación con useAirbagTelematics: false, pero los dos campos se resuelven por separado: no asumas que la presencia de uno determina el valor del otro.
emergencyContact	Object	Opcional	Contacto de emergencia del conductor. Ver Campos dentro de emergencyContact.

La configuración de la app móvil no forma parte de este contrato

Las preferencias que controlan qué muestra la aplicación del conductor se administran desde el panel de Airbag y no se publican en esta API. Si tu integración necesita consultarlas o modificarlas, escríbenos a soporte.

Gamificación

Campo	Tipo	Presencia	Descripción
coins	Number	Siempre	Monedas acumuladas por el conductor en el sistema de gamificación.
redeemCount	Number	Opcional	Número de canjes realizados por el conductor.
hasMadeFirstTrip	Boolean	Opcional	true cuando el conductor ya completó su primer viaje. Se inicializa en false al crear el conductor, por lo que está ausente sólo en registros heredados anteriores al programa de bonos.
hasClaimedWelcomeBonus	Boolean	Opcional	true cuando el conductor ya reclamó el bono de bienvenida, las monedas que otorga el primer inicio de sesión. Se inicializa en false al crear el conductor. Ausente en registros heredados, donde la plataforma lo interpreta como bono ya reclamado.
hasClaimedFirstTripBonus	Boolean	Opcional	true cuando el conductor ya reclamó el bono por su primer viaje. Sólo puede reclamarse si hasMadeFirstTrip es true. Se inicializa en false al crear el conductor. Ausente en registros heredados, donde la plataforma lo interpreta como bono ya reclamado.
currentLevel	Object	Opcional	Nivel actual del conductor en el sistema de gamificación. Ver Campos dentro de currentLevel. Ausente mientras no tenga distancia acumulada.
currentStreak	Object	Opcional	Racha de días activos del conductor. Ver Campos dentro de currentStreak. Ausente mientras no tenga actividad registrada.

⚠️

Los indicadores de bono describen progreso, no saldo

hasMadeFirstTrip, hasClaimedWelcomeBonus y hasClaimedFirstTripBonus sólo indican si el conductor alcanzó el hito y si reclamó las monedas correspondientes. El monto de cada bono lo define la empresa y no viaja en esta respuesta; el saldo vigente está en coins. Los reclamos se realizan desde la app móvil, así que los tres campos son de sólo lectura y no pueden modificarse desde esta API.

Campos dentro de license

Presente sólo cuando el conductor registró su licencia desde la app móvil. Los tres subcampos viajan juntos.

Campo	Tipo	Descripción
number	String	Número o folio impreso en la licencia de conducir. Ejemplo: A1234567
type	String	Tipo o categoría de la licencia, tal como la capturó el conductor. Es texto libre y su valor depende de la nomenclatura del país que la emite (por ejemplo federal, A, B).
expiration	String	Fecha de vencimiento de la licencia en formato ISO 8601. Ejemplo: 2027-11-30T00:00:00.000Z

Campos dentro de emergencyContact

Campo	Tipo	Descripción
name	String	Nombre de la persona de contacto.
phone	String	Teléfono del contacto con código de país.
type	String	Tipo de teléfono. Valores: cellphone o landphone.

Campos dentro de currentLevel

Campo	Tipo	Descripción
levelId	String	Identificador único del nivel actual.
name	String	Nombre legible del nivel (por ejemplo Nivel 3).
maxLevel	Number	Número total de niveles disponibles en el programa.
from	Number	Distancia (en km) que marca el inicio del nivel.
to	Number	Distancia (en km) que marca el final del nivel.
targetDistance	Number	Distancia objetivo a recorrer dentro del nivel actual.
currentDistance	Number	Distancia recorrida dentro del nivel actual.
remainingDistance	Number	Distancia restante para completar el nivel.
totalDistanceTravelled	Number	Distancia total acumulada por el conductor desde el inicio del programa.
percentageCompleted	Number	Porcentaje de avance del nivel actual (0–100).

Campos dentro de currentStreak

Campo	Tipo	Descripción
isInStreak	Boolean	true si el conductor mantiene una racha activa.
totalDaysOfStreak	Number	Días consecutivos que conforman la racha actual.
maxHistoricalStreak	Number	Racha más larga alcanzada históricamente.
lastDayWithTrips	String	Último día con viajes registrados (ISO 8601).
lastWeekDaysStreak	Array<Object>	Detalle día a día de la actividad reciente. Ver tabla abajo.

Campos dentro de cada elemento de lastWeekDaysStreak

Campo	Tipo	Descripción
date	String	Fecha del día en formato ISO 8601.
dayCharacter	String	Inicial del día en español (L, M, X, J, V, S, D).
dayOfWeek	String	Día de la semana en inglés y minúsculas (monday, tuesday, …).
streak	String	Estado de la racha para ese día. Valores: IN_STREAK_ACTIVE (día dentro de la racha, con viajes), IN_STREAK_INACTIVE (día dentro de la racha, sin viajes, tolerado por el programa) y OUT_OF_STREAK (día fuera de la racha).

nota

Los registros anteriores a la normalización de este bloque pueden traer una clave adicional, completeDescriptionDay, remanente de un formato previo en el que dayOfWeek guardaba sólo la inicial del día. El sistema la elimina al recalcular la racha del conductor. No forma parte del contrato: ignórala.

⚠️

Ignora las claves que no aparezcan en estas tablas

El contrato público de este endpoint es el conjunto de campos documentado arriba. La respuesta puede incluir además claves de uso interno de la plataforma, como identificadores de integraciones con terceros o marcas de procesos de migración, que no forman parte del contrato: pueden cambiar de forma, renombrarse o desaparecer sin aviso previo. Descártalas y no construyas lógica sobre ellas.

❌ Respuesta con error (400 Bad Request)

Se devuelve cuando el DRIVER_ID no corresponde a ningún conductor de tu empresa.

{
  "status": false,
  "message": "Error: Driver ID was not found",
  "errorId": "sentry_error_id_123"
}