Reporte de Mantenimiento

Estado actual de mantenimiento de tu flota — kilómetros restantes, horas hasta el servicio y elementos vencidos. Una instantánea en tiempo real, sin rango de fechas requerido.

GET/apidev/v1/reports/avl/maintenance

PermisoAPICLI_RPTAVL_MANTENIMIENTO

Límite de solicitudes10 req/min (ventana deslizante)

Caché300s (5 min)

---

Resumen

Instantánea en tiempo real del estado de mantenimiento preventivo. A diferencia de otros reportes AVL, este endpoint no lleva parámetros de fecha — devuelve el estado actual de cada programa de mantenimiento.

• Programas al día por defecto — sin overdue_only, lista los programas con servicio pendiente a futuro (next_service_value > 0)
• Detección de vencidos — overdue_only=true lista solo los programas vencidos (next_service_value <= 0)
• Filtrado por programa — maintenance_ids restringe a programas de mantenimiento específicos
• Kms u horas — los valores están en kilómetros o en horas de ignición según el tipo de período del programa (maintenance_period)

Sin rango de fechas

Este endpoint devuelve el estado actual de mantenimiento, no datos históricos. No requiere startdate/enddate.

---

Solicitud

Encabezados de la solicitud

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Parámetros de consulta

Parámetro	Tipo	Requerido	Predeterminado	Descripción
devices	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500
maintenance_ids	string	No	Todos	IDs de programa de mantenimiento separados por coma. Máximo 100
overdue_only	boolean	No	false	false = programas al día (next_service_value > 0). true = solo programas vencidos (next_service_value <= 0)
limit	integer	No	25	Registros por página (1–100)
offset	integer	No	0	Registros a omitir

---

Ejemplos de código

cURL

curl -s "https://$TENANT/apidev/v1/reports/avl/maintenance?limit=50&overdue_only=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/maintenance?limit=50&overdue_only=true`,
  { headers }
);
const { data, meta } = await response.json();

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/maintenance",
    headers=headers,
    params={"limit": 50, "overdue_only": True},
)
result = response.json()

---

Campos de la respuesta

Campo	Tipo	Descripción
maintenance_name	string	Nombre del programa de mantenimiento (ej. "Cambio de aceite")
maintenance_period	string	Tipo de período del programa: "Kms recorridos" / "Horas de ignición" / "Cada cantidad de días" / "Fecha específica"
maintenance_value	number	Valor del intervalo del programa (ej. cada 7500 kms)
device_name	string	Nombre visible del vehículo/dispositivo
last_service_value	number | null	Odómetro/horómetro al momento del último servicio. null si nunca se realizó
next_service_value	number | null	Cuánto falta para el próximo servicio. <= 0 = vencido
current_value	number | null	Odómetro/horómetro actual del vehículo
remaining_value	number | null	Cuánto consumió el vehículo desde el último servicio

Kms u horas según el período

Los campos maintenance_value, last_service_value, next_service_value, current_value y remaining_value están en kilómetros o en horas según el tipo de período del programa (maintenance_period). En los períodos por días o por fecha específica, los campos de valores vienen null.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "maintenance_name": "Service 7500 km",
      "maintenance_period": "Kms recorridos",
      "maintenance_value": 7500,
      "device_name": "Truck A-101",
      "last_service_value": 191175,
      "next_service_value": 130,
      "current_value": 198545,
      "remaining_value": 7370
    },
    {
      "maintenance_name": "Cambio de filtros",
      "maintenance_period": "Horas de ignición",
      "maintenance_value": 500,
      "device_name": "Van B-205",
      "last_service_value": 1800,
      "next_service_value": 150,
      "current_value": 2150,
      "remaining_value": 350
    }
  ],
  "meta": {
    "total": 12,
    "limit": 50,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos: IDs no numéricos, limit > 100, > 500 dispositivos, > 100 maintenance_ids
UNAUTHORIZED	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN	403	El usuario carece del permiso APICLI_RPTAVL_MANTENIMIENTO
RATE_LIMITED	429	Se superaron las 10 req/min
INTERNAL_ERROR	500	Error inesperado del servidor

---

Relacionado

• API de Dispositivos — Obtené IDs de dispositivo y odómetro actual
• Reporte de Ignición — Seguimiento de horas de motor
• Paginación — Parámetros de paginación estándar