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). Debe usarse junto con `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",
      "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"
    }
    // … (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`).
`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).

❌ 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.

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

Errores comunes de validación:

Usar direction sin especificar sort
Especificar startDate sin endDate (o viceversa)
Usar un campo de ordenamiento no válido en sort
Combinar fechas 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.
Vista general primero: usa este endpoint para obtener el listado general, luego consulta detalles individuales cuando necesites información completa (email, teléfono, rol, etc.).
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​