Paginación y envoltorio de respuesta

Todos los endpoints de la API siguen un envoltorio de respuesta consistente. Los endpoints de listado soportan paginación basada en offset.

Envoltorio de respuesta

Cada respuesta — exitosa o de error — se envuelve en un envoltorio estándar. Esto hace que sea seguro verificar siempre success primero antes de acceder a data.

Endpoints de listado

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 150,
    "limit": 25,
    "offset": 0
  }
}

Campo	Tipo	Descripción
success	boolean	true cuando la solicitud se completó sin errores
data	array	Los recursos coincidentes para esta página
meta.total	integer	Total de registros que coinciden con la consulta después de filtros, antes de paginar
meta.limit	integer	Cantidad de registros devueltos en esta página
meta.offset	integer	Cantidad de registros omitidos (posición de inicio)

Endpoints de recurso único

Los endpoints GET-por-ID devuelven data como un objeto, no un array. El campo meta puede estar vacío u omitirse:

{
  "success": true,
  "data": {
    "id": "104820579301",
    "name": "Truck-42",
    "plate": "ABC-1234",
    "status": "A"
  },
  "meta": {}
}

Operaciones de escritura (POST / PUT)

Los endpoints de creación y actualización devuelven el recurso creado o actualizado en data:

{
  "success": true,
  "data": {
    "id": "104820579305",
    "name": "Truck-New",
    "plate": "XYZ-9999",
    "status": "A",
    "createdAt": "2026-04-04T14:30:00"
  },
  "meta": {}
}

Respuestas de error

Cuando ocurre un error, data siempre es null y el objeto error contiene los detalles. Ver Manejo de errores para la referencia completa.

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "\"limit\" must be a number between 1 and 100"
  }
}

---

Paginación

Los endpoints de listado soportan paginación limit/offset mediante parámetros de consulta:

Parámetro	Tipo	Por defecto	Máx	Descripción
limit	integer	25	100	Cantidad de registros por página
offset	integer	0	—	Cantidad de registros a omitir. En los reportes avanza de a páginas completas — ver abajo

Ejemplos

Primera página (por defecto):

GET /apidev/v1/fleet/devices?limit=25&offset=0
→ records 1–25

Segunda página:

GET /apidev/v1/fleet/devices?limit=25&offset=25
→ records 26–50

Tercera página:

GET /apidev/v1/fleet/devices?limit=25&offset=50
→ records 51–75

Los reportes paginan de a pasos completos de limit

Los reportes (/reports/**) avanzan de a páginas completas, así que el offset se redondea hacia abajo al múltiplo de limit más cercano. Pedir limit=25&offset=30 devuelve la misma página que offset=25.

Siempre sabés qué recibiste: meta.offset informa el offset realmente aplicado, no el que pediste. Si mantenés el offset como múltiplo del limit (0, 25, 50, …), el comportamiento es exactamente el esperado.

Calcular el total de páginas

const totalPages = Math.ceil(meta.total / meta.limit);
// total: 150, limit: 25 → 6 pages

Iterar por todas las páginas

JavaScript

async function fetchAllPages(baseUrl, headers) {
  const limit = 100;
  let offset = 0;
  let allRecords = [];

  while (true) {
    const response = await fetch(
      `${baseUrl}?limit=${limit}&offset=${offset}`,
      { headers }
    );
    const json = await response.json();

    allRecords = allRecords.concat(json.data);

    if (offset + limit >= json.meta.total) break;
    offset += limit;
  }

  return allRecords;
}

// Usage
const devices = await fetchAllPages(
  `https://${TENANT}/apidev/v1/fleet/devices`,
  headers
);

Python

def fetch_all_pages(base_url, headers):
    limit = 100
    offset = 0
    all_records = []

    while True:
        response = requests.get(
            base_url,
            headers=headers,
            params={"limit": limit, "offset": offset},
        )
        json_data = response.json()

        all_records.extend(json_data["data"])

        if offset + limit >= json_data["meta"]["total"]:
            break
        offset += limit

    return all_records

# Usage
devices = fetch_all_pages(
    f"https://{TENANT}/apidev/v1/fleet/devices",
    headers
)

tip

Configurá limit=100 (el máximo) al iterar por todas las páginas para minimizar la cantidad de llamadas a la API y mantenerte dentro de los límites de solicitudes.

---

Filtros y paginación

Los filtros se aplican antes de la paginación. El valor meta.total refleja el conteo de registros que coinciden con tus filtros, no el total en la base de datos.

GET /apidev/v1/fleet/devices?status=A&limit=25&offset=0

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 42,
    "limit": 25,
    "offset": 0
  }
}

En este ejemplo, 42 dispositivos tienen status=A — no 42 dispositivos en total en el sistema. Los cálculos de páginas deben usar este total filtrado.

---

Orden de clasificación

Los endpoints de listado devuelven resultados en un orden determinístico, típicamente por clave primaria o fecha de creación descendente (los más nuevos primero). La documentación de cada endpoint especifica el orden por defecto cuando difiere de esta convención.

La API no expone un parámetro de consulta sort genérico — el orden de clasificación es fijo por endpoint para garantizar una paginación consistente entre páginas.

---

Resultados vacíos

Cuando una consulta no coincide con ningún registro, la respuesta usa el envoltorio estándar con un array vacío:

{
  "success": true,
  "data": [],
  "meta": {
    "total": 0,
    "limit": 25,
    "offset": 0
  }
}

Esto no es un error — success es true. Tu código debe manejar arrays data vacíos de forma adecuada en lugar de tratarlos como fallas.

aviso

El valor máximo permitido para limit es 100. Solicitar un valor mayor devuelve un VALIDATION_ERROR.