🖥️

InvCompu API

Sistema de Inventario y Gestión de Sala de Computación

ℹ️

API REST construida con Django 6 y Django REST Framework 3.16. Todas las rutas están bajo el prefijo /api/v1/. Los recursos se entregan en formato JSON. Autenticación mediante JWT con algoritmo HS512.

30

Endpoints

6

Modelos

4

Módulos

REST

Arquitectura

🗄️

Módulo Inventario

Gestión de dispositivos (categorías de hardware), equipos físicos y consumibles del laboratorio. CRUD completo con paginación y filtrado por tipo.

Ver documentación →

🏫

Módulo Sala de PCs

Administración de profesores y reservas de uso de la sala de computación. Control de quién usa el laboratorio, cuándo y con qué curso.

Ver documentación →

🔐

Módulo Seguridad

Registro de usuarios, autenticación JWT y gestión de perfiles. Dos niveles de permisos: admin y profesor.

Ver documentación →

📊

Módulo Dashboard

Panel de resumen con total de equipos registrados y la agenda semanal de uso de la sala de PCs.

Ver documentación →

Base URL

Todas las peticiones a la API deben incluir este prefijo.

Producción

      https://backend-inventario-computadores-production.up.railway.app/api/v1/

Desarrollo local

      http://127.0.0.1:8000/api/v1/

⚠️

En desarrollo local el host habitual es http://127.0.0.1:8000. El servidor de producción está desplegado en Railway: https://backend-inventario-computadores-production.up.railway.app.

Paginación

Todos los listados devuelven resultados paginados con la siguiente estructura.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
page	integer	1	Número de página a retornar.
page_size	integer	10 (Inventario) / 20 (SalaPC)	Cantidad de registros por página (máx. 50). En el módulo SalaPC el parámetro se llama `Limit`.

Estructura de respuesta paginada

      {
  "links": {
    "next":     "http://127.0.0.1:8000/api/v1/dispositivos?page=2",
    "previous": null
  },
  "items":  42,
  "status": "ok",
  "page":   "1/5",
  "data":   [ ... ]
}
    

Campo	Tipo	Descripción
links.next	string \| null	URL de la siguiente página, o `null` si es la última.
links.previous	string \| null	URL de la página anterior, o `null` si es la primera.
items	integer	Total de registros en la base de datos para ese recurso.
status	string	Estado de la operación: siempre `"ok"` en listados exitosos.
page	string	Página actual sobre total de páginas (ej. `"2/5"`).
data	array	Lista de objetos del recurso solicitado.

Códigos de Respuesta

La API utiliza los siguientes códigos HTTP estándar.

Código	Significado	Descripción
200 OK	Éxito	Petición procesada correctamente (GET, PUT, DELETE).
201 Created	Recurso creado	El recurso fue creado exitosamente (POST).
400 Bad Request	Error de validación	Los datos enviados no pasaron la validación o hay un error en la petición.
401 Unauthorized	Sin autorización	Token JWT ausente, inválido o expirado.
403 Forbidden	Permisos insuficientes	El usuario no tiene rol de administrador para esta operación (DELETE).
404 Not Found	No encontrado	El recurso solicitado no existe en la base de datos.
409 Conflict	Conflicto de recurso	La operación choca con el estado actual. Ej.: reservar la sala en una fecha y hora ya ocupadas.
429 Too Many Requests	Límite de peticiones	Se superó el límite de 1000 peticiones diarias para usuarios anónimos.

Estructura de respuestas comunes

Éxito en operación

      {
  "status":  "ok",
  "message": "Registro creado exitosamente"
}
    

Error de validación (400)

      {
  "status":  "error",
  "message": {
    "campo": ["Este campo es obligatorio."]
  }
}
    

Error de autenticación (401)

      {
  "error": "Token de autenticación es requerido"
}
    

Autenticación

La mayoría de los endpoints requieren un token JWT válido.

⚠️

Los endpoints de registro (/api/v1/seguridad/reg) y login (/api/v1/seguridad/login) son públicos. Todos los demás requieren el header Authorization.

Header requerido en peticiones protegidas

HTTP Header

      Authorization: Bearer <token>

Niveles de acceso

Nivel	Rol requerido	Operaciones
🔒 login	Cualquier usuario autenticado	GET, POST, PUT en todos los módulos
🛡️ admin	Solo usuarios con rol `admin`	DELETE en todos los módulos

Escenario	Código	Mensaje
Header `Authorization` ausente	401	`"Token de autenticación es requerido"`
Token inválido / malformado	401	`"Token de autenticación inválido"`
Token expirado	401	`"Token ha expirado"`
Rol insuficiente (no admin)	403	`"Permisos insuficientes"`

Para obtener un token, utiliza el endpoint POST /api/v1/seguridad/login. El token tiene una validez de 24 horas y utiliza el algoritmo HS512.

Rate Limiting

La API aplica límites de peticiones para proteger el servidor de uso excesivo.

⚠️

El throttle solo aplica a peticiones anónimas (sin token JWT válido). Las peticiones autenticadas no tienen límite configurado actualmente.

Tipo de cliente	Límite	Ventana	Identificador
Anónimo (sin token)	60 peticiones	Por minuto	IP de origen

Al superar el límite, la API devuelve 429 Too Many Requests con el header Retry-After indicando los segundos hasta que el contador se reinicia.