Consultar sub-compañías

[ GET ]

Consulta las sub-compañías que dependen de tu compañía padre, junto con su país, estado y el número de conductores y administradores registrados en cada una. Este endpoint no genera cambios sobre los datos.

https://sync.airbagtech.io/company/sub-companies

🔒

La compañía padre se deriva de la API key

Esta ruta no acepta un campo companyId. La compañía padre se resuelve siempre a partir de la API key con la que firmas la solicitud, por lo que no es posible consultar la jerarquía de una organización ajena. Usa la llave de la compañía padre: una llave de sub-compañía devolverá su propia jerarquía, normalmente vacía.

Campos

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. Se envía como parámetro de consulta (query param).
size	Number	No	Número de sub-compañías por página. Debe ser un entero entre 1 y 500. Si no se envía, por defecto es 50. Se envía como parámetro de consulta (query param).

Headers

Autorization
apikey {{API_KEY}}

Ejemplo

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

Ejemplo con paginación

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

Respuestas

✅ Respuesta exitosa (200 OK)

Devuelve la ficha de la compañía padre (parentCompany), el arreglo childCompanies con las sub-compañías de la página solicitada, el total de sub-compañías del grupo (total) y los metadatos de paginación.

{
  "status": true,
  "parentCompany": {
    "id": "a1b2c3d4e5f6g7h8i9j0k1l2",
    "name": "Grupo Ejemplo"
  },
  "childCompanies": [
    {
      "id": "b2c3d4e5f6g7h8i9j0k1l2m3",
      "name": "Distribuidora Norte",
      "status": "active",
      "country": "MX",
      "managersCount": 4,
      "driversCount": 128
    },
    {
      "id": "c3d4e5f6g7h8i9j0k1l2m3n4",
      "name": "Logística Bajío",
      "status": "active",
      "country": "MX",
      "managersCount": 2,
      "driversCount": 43
    },
    {
      "id": "d4e5f6g7h8i9j0k1l2m3n4o5",
      "name": "Transportes Andinos",
      "status": "inactive",
      "country": "CO",
      "managersCount": 1,
      "driversCount": 0
    }
  ],
  "total": 3,
  "pagination": {
    "currentPage": 1,
    "size": 50,
    "totalPages": 1,
    "hasNext": false
  }
}

nota

Si tu compañía no tiene sub-compañías asociadas, la respuesta sigue siendo 200 OK con childCompanies: [], total: 0 y totalPages: 0. Esta ruta no devuelve 404 cuando la lista está vacía.

Descripción de campos de respuesta

Campo	Tipo	Descripción
status	Boolean	Indica si la operación fue exitosa.
parentCompany	Object	Datos de la compañía padre, deducida de la API key. Ver tabla abajo.
childCompanies	Array<Object>	Sub-compañías incluidas en la página solicitada, ordenadas alfabéticamente por name. Ver tabla abajo.
total	Number	Número total de sub-compañías del grupo, independientemente de la paginación.
pagination	Object	Metadatos de paginación. Ver tabla abajo.

Campos dentro de parentCompany

Campo	Tipo	Descripción
id	String	Identificador interno de la compañía padre en la plataforma Airbag.
name	String	Nombre registrado de la compañía padre. Puede ser null si el perfil no está disponible.

Campos dentro de cada elemento de childCompanies

Campo	Tipo	Descripción
id	String	Identificador interno de la sub-compañía en la plataforma Airbag. Úsalo como llave estable de correlación con tus sistemas.
name	String	Nombre registrado de la sub-compañía. Se lee siempre de la ficha de la compañía, por lo que refleja el nombre vigente.
status	String	Estado de la sub-compañía en la plataforma. Valores: active o inactive.
country	String	País en formato ISO 3166-1 alfa-2 en mayúsculas (MX, CO, PE, AR, BR, CL, CR, EC, ES, PA, US, BO, GT). Devuelve null si el país registrado no tiene traducción conocida.
managersCount	Number	Administradores registrados en la sub-compañía, contados en el momento de la consulta. Incluye tanto activos como inactivos.
driversCount	Number	Conductores registrados en la sub-compañía, contados en el momento de la consulta. Incluye tanto activos como inactivos.

Campos dentro de pagination

Campo	Tipo	Descripción
currentPage	Number	Página devuelta.
size	Number	Tamaño de página aplicado.
totalPages	Number	Número total de páginas disponibles para el size usado.
hasNext	Boolean	true si existe una página posterior. Recorre la lista hasta que valga false.

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

Se devuelve cuando page o size están fuera de rango. Si ambos son inválidos, 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 no es un entero o queda fuera del rango permitido.

❌ 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"
}

❌ Error inesperado (500 Internal Server Error)

{
  "status": false,
  "message": "Unexpected error",
  "errorId": "sentry_error_id_123"
}

Guarda el errorId y compártelo con el equipo de soporte para acelerar la revisión.

Recomendaciones

La jerarquía cambia con poca frecuencia: cachea el resultado en lugar de consultarlo en cada ciclo de sincronización. Ten en cuenta que el total y la página se calculan en dos lecturas distintas, por lo que si una sub-compañía se da de baja entre ambas el total puede quedar una unidad por encima de lo que suman las páginas. Consultar la jerarquía no otorga acceso a los datos de las filiales: para leer sus conductores o viajes necesitas la API key de cada sub-compañía.