Consultar todos los administradores

[ GET ]

Visión general

Recupera el listado de todos los administradores asociados a tu organización. Este endpoint permite paginar resultados, ordenar por diferentes criterios y filtrar por rango de fechas, facilitando la gestión de grandes equipos y la generación de reportes administrativos.

URL: https://sync.airbagtech.io/manager
Uso principal: auditorías de accesos, revisión de equipos operativos
Consideración: combina los parámetros de consulta para obtener vistas específicas del equipo.

Autenticación

Incluye el encabezado Authorization: apikey {API_KEY}. Las claves API se solicitan al equipo de soporte de Airbag Tech y se asignan a contactos autorizados dentro de la organización.

Encabezados

Encabezado	Valor	Descripción
`Authorization`	`apikey {API_KEY}`	Clave única solicitada al equipo de soporte para validar la llamada.

Parámetros de consulta

Todos los parámetros son opcionales y pueden combinarse para refinar los resultados.

Parámetro	Tipo	Requerido	Descripción
`limit`	Number	No	Número máximo de administradores a devolver. Útil para implementar paginación del lado del cliente.
`sort`	String	No	Campo por el cual ordenar los resultados. Valores válidos: `fullName`, `lastName`, `gender`, `authRole`, `created`, `status`.
`direction`	String	No	Dirección del ordenamiento. Valores válidos: `asc` (ascendente) o `desc` (descendente). Tiene efecto cuando se envía `sort`.
`startDate`	String	No	Fecha inicial del rango de búsqueda en formato ISO 8601 (`YYYY-MM-DD`). Debe usarse junto con `endDate`.
`endDate`	String	No	Fecha final del rango de búsqueda en formato ISO 8601 (`YYYY-MM-DD`). Debe usarse junto con `startDate`.

ℹ️

Nota sobre ordenamiento por fechas

Si utilizas los parámetros startDate y endDate, el campo sort debe ser created o no especificarse. Esta restricción asegura consistencia en las consultas temporales.

Ejemplos de solicitud

Consulta básica (todos los administradores)

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

Consulta con paginación

curl --location -g 'https://sync.airbagtech.io/manager?limit=10' \
  --header 'Authorization: apikey ${API_KEY}'

Consulta con ordenamiento

curl --location -g 'https://sync.airbagtech.io/manager?sort=fullName&direction=asc' \
  --header 'Authorization: apikey ${API_KEY}'

Consulta con rango de fechas

curl --location -g 'https://sync.airbagtech.io/manager?startDate=2024-01-01&endDate=2024-12-31' \
  --header 'Authorization: apikey ${API_KEY}'

Consulta combinada

curl --location -g 'https://sync.airbagtech.io/manager?limit=20&sort=created&direction=desc&startDate=2024-01-01&endDate=2024-12-31' \
  --header 'Authorization: apikey ${API_KEY}'

Respuestas

✅ Respuesta exitosa (200 OK)

Devuelve el número total de administradores registrados (length) y un arreglo managers con la ficha de cada uno.

{
  "status": true,
  "length": 60,
  "managers": [
    {
      "authRole": "admin",
      "created": "2024-02-05T00:19:14.555Z",
      "email": "[email protected]",
      "fullName": "Ana Martínez López",
      "groups": [],
      "lastName": "Martínez López",
      "name": "Ana",
      "phone": "+525512345678",
      "gender": "female",
      "status": "active",
      "coins": 0,
      "airbagId": "Kp9qLmRsT2uVwXyZaBcD",
      "company": "Transportes Ejemplo",
      "id": "Kp9qLmRsT2uVwXyZaBcD"
    },
    {
      "authRole": "admin",
      "created": "2023-08-12T19:39:46.075Z",
      "email": "[email protected]",
      "fullName": "Roberto Sánchez",
      "groups": [],
      "lastName": "Sánchez",
      "name": "Roberto",
      "phone": "+525598765432",
      "status": "active",
      "coins": 0,
      "airbagId": "Np7QrSt8UvWxYz0AbCdE",
      "company": "Transportes Ejemplo",
      "id": "Np7QrSt8UvWxYz0AbCdE"
    },
    {
      "authRole": "group-limited",
      "created": "2022-07-06T16:52:43.634Z",
      "email": "[email protected]",
      "fullName": "Carla Ríos",
      "groups": [
        "grp_A1b2C3d4E5f6G7h8I9j0",
        "grp_K1l2M3n4O5p6Q7r8S9t0"
      ],
      "lastName": "Ríos",
      "name": "Carla",
      "phone": "+525544332211",
      "status": "active",
      "coins": 0,
      "airbagId": "Lm8NpQrSt2UvWxYzAbCd",
      "company": "Transportes Ejemplo",
      "id": "Lm8NpQrSt2UvWxYzAbCd"
    },
    {
      "authRole": "admin",
      "created": "2025-06-25T18:34:32.595Z",
      "email": "[email protected]",
      "fullName": "Josué García",
      "groups": [],
      "lastName": "García",
      "name": "Josué",
      "phone": "+525566778899",
      "status": "active",
      "coins": 0,
      "airbagId": "Qr3StUv4WxYz5aBcDeFg",
      "company": "Transportes Ejemplo",
      "id": "Qr3StUv4WxYz5aBcDeFg"
    }
  ]
}

Ejemplo abreviado: la respuesta real continúa con el resto de administradores hasta completar los 60 elementos.

nota

managers contiene hasta limit elementos (o todos los existentes cuando no se especifica limit).
Los administradores con authRole: "admin" suelen tener groups: [] (acceso global); los group-limited traen al menos un ID de grupo en groups.
El campo id y airbagId suelen coincidir cuando el administrador no fue creado con un ID personalizado.

Descripción de campos de respuesta

Campo	Tipo	Descripción
`status`	Boolean	Indica si la operación fue exitosa.
`length`	Number	Número total de administradores devueltos en `managers`.
`managers`	Array<Object>	Lista de administradores con sus datos completos. Ver tabla abajo.

Campos dentro de cada elemento de `managers`

Campo	Tipo	Descripción
`airbagId`	String	Identificador interno único en la plataforma Airbag. Útil para operaciones internas y referencias cruzadas.
`id`	String	Identificador del administrador. Coincide con `airbagId` cuando no se proporcionó un ID personalizado al crearlo; en caso contrario, es el ID definido por tu empresa.
`company`	String	Nombre de la organización a la que pertenece el administrador.
`fullName`	String	Nombre completo del administrador (`name` + `lastName`).
`name`	String	Nombre de pila del administrador.
`lastName`	String	Apellido del administrador.
`email`	String	Correo electrónico corporativo. Canal principal de comunicación y autenticación.
`phone`	String	Número de teléfono con código de país (formato `+525555555555`).
`gender`	String	Género del administrador. Valores: `male`, `female`, `other`. Es un campo opcional: la clave está ausente en la respuesta cuando no se informó al crear la cuenta. También es un criterio válido para `sort`.
`authRole`	String	Rol de permisos asignado. Valores: `admin` (acceso total) o `group-limited` (acceso restringido a los grupos listados en `groups`).
`groups`	Array<String>	IDs de los grupos a los que tiene acceso. Suele estar vacío (`[]`) cuando `authRole` es `admin`.
`status`	String	Estado de la cuenta. Valores: `active` o `inactive`.
`coins`	Number	Saldo de monedas acumulado por el administrador. Generalmente `0` salvo que la empresa otorgue monedas a su equipo administrativo.
`created`	String	Fecha y hora de creación de la cuenta en formato ISO 8601 (UTC).

Los campos opcionales que no fueron informados no viajan en el JSON: la clave se omite en lugar de llegar como null. Comprueba que exista antes de leerla.

❌ Sin resultados (404 Not Found)

Se devuelve cuando no existen administradores que cumplan con los criterios de búsqueda.

{
  "status": true,
  "message": "No managers found with given parameters",
  "length": 0,
  "managers": []
}

⚠️ Error en la solicitud (400 Bad Request)

Se devuelve cuando los parámetros de consulta son inválidos. Si hay varios errores, los mensajes llegan separados por comas.

{
  "status": false,
  "message": "Direction must be 'asc' or 'desc' but xyz was found"
}

Errores de validación:

direction distinto de asc o desc
limit que no es un número
startDate sin endDate (o viceversa), una fecha inválida o startDate no anterior a endDate
Un campo de ordenamiento no válido en sort
Fechas combinadas con un campo sort diferente a created

Respuestas y buenas prácticas

200 OK: devuelve el array completo con todos los administradores que cumplen los criterios.
404 No encontrado: confirma que existen administradores registrados en la organización.
400 Solicitud incorrecta: verifica la sintaxis de los parámetros de consulta.

Recomendaciones

Paginación eficiente: utiliza limit para evitar sobrecargar la respuesta cuando gestionas equipos grandes.
Ordenamiento consistente: mantén el mismo criterio de sort y direction en consultas subsecuentes para una experiencia predecible.
Filtrado por fechas: ideal para auditorías mensuales o trimestrales; combina con sort=created para orden cronológico.
Mismos campos que el detalle: cada elemento trae los mismos campos que Consultar administrador, así que no necesitas consultar el detalle para obtener email, teléfono o rol.
Referencia por ID: utiliza el campo id para realizar operaciones específicas en otros endpoints (actualizar, eliminar, consultar detalle).

Casos de uso

Listado general: obtén una vista rápida de todos los administradores registrados en la organización.
Dashboards y reportes: muestra nombres y conteo de administradores en interfaces de administración.
Sincronización de sistemas: mantén actualizada la lista de administradores en sistemas externos usando el airbagId como referencia.
Verificación de registro: confirma que los nuevos administradores se hayan creado correctamente consultando por fecha.
Exportación básica: genera listados simples con nombres e identificadores para reportes ejecutivos.

Visión general​

Autenticación​

Encabezados​

Parámetros de consulta​

Ejemplos de solicitud​

Consulta básica (todos los administradores)​

Consulta con paginación​

Consulta con ordenamiento​

Consulta con rango de fechas​

Consulta combinada​

Respuestas​

✅ Respuesta exitosa (200 OK)​

Descripción de campos de respuesta​

Campos dentro de cada elemento de managers​

❌ Sin resultados (404 Not Found)​

⚠️ Error en la solicitud (400 Bad Request)​

Respuestas y buenas prácticas​

Recomendaciones​

Casos de uso​