Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Danielings/Pasantia-Proyecto/llms.txt
Use this file to discover all available pages before exploring further.
The Sistema de Inventario Tecnológico exposes a REST API built with Express.js and backed by Firebase Firestore. Every feature available in the frontend — managing users, registering equipment, tracking peripherals, querying locations, exporting reports, and reviewing the audit log — is accessible through this API. This page describes the conventions that apply to every endpoint so you can integrate or test any part of the system consistently.
Base URL
All endpoints are mounted under the /api prefix. During local development the server binds to port 3001.
http://localhost:3001/api
http://localhost:3001 with your production host when deploying. Every path shown in this documentation is relative to this base URL (e.g. POST /login means POST http://localhost:3001/api/login).
Authentication Model
The API uses JWT cookie-based authentication. There are no Authorization headers to manage manually — the session token is issued as an HTTP-only cookie named acceso_token when you call POST /api/login and is cleared automatically on POST /api/logout.
Because the token lives in an HTTP-only cookie, JavaScript running in the browser cannot read it directly. All requests that require authentication must be made with credentials included so the browser attaches the cookie automatically.
withCredentials: true on every request. For command-line tools such as curl, use a cookie jar (-c to save, -b to send). Protected routes return 401 immediately if the cookie is absent or the JWT has expired. See the Authentication page for full details.
Content Type
All request bodies must be sent as JSON and all responses are returned as JSON, with two exceptions:
| Endpoint group | Response content type |
|---|
| All other endpoints | application/json |
GET /export/descargar (PDF) | application/pdf |
GET /export/descargar (Excel) | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Content-Type: application/json header when sending a request body.
CORS
The server is pre-configured to accept cross-origin requests with credentials from the Vite development server:
Origin: http://localhost:5173
Credentials: enabled
Allowed methods: GET, POST, PUT, DELETE
Allowed headers: Content-Type, Authorization
Exposed headers: Content-Disposition
If you host the frontend on a different origin in production you must update the origin value in the CORS configuration on the server. Requests from unlisted origins will be rejected by the browser before they reach the API.
HTTP Status Codes
The API uses a consistent set of HTTP status codes across all resources.
| Code | Meaning | When it is returned |
|---|
200 OK | Success | Successful read (GET) or update (PUT) |
201 Created | Resource created | Successful POST that created a new document |
400 Bad Request | Validation error | Missing required fields, invalid format, or failed business-rule check |
401 Unauthorized | Authentication required | Cookie is absent, expired, or the JWT cannot be verified |
403 Forbidden | Insufficient permissions | Authenticated user’s role does not permit the action |
404 Not Found | Resource missing | The requested document ID does not exist in Firestore |
409 Conflict | Duplicate resource | Duplicate serial number, username, cedula, or location |
500 Internal Server Error | Unexpected error | Unhandled exception or Firestore failure |
Error Response Shape
Every error response — regardless of status code — uses the same JSON envelope:
{
"message": "Human-readable description of the error."
}
Always read the message field when handling non-2xx responses. Validation errors (400) include a specific description of which field failed and why, which you can surface directly in your UI.
Endpoint Index
The tables below list every available endpoint organized by resource group. All paths are relative to http://localhost:3001/api.
Auth
| Method | Path | Description | Auth required |
|---|
POST | /login | Authenticate and receive the session cookie | No |
POST | /logout | Clear the session cookie | No |
GET | /me | Return the JWT payload for the current session | Yes |
GET | /usuarios/me | Return the full Firestore user document for the current session | Yes |
Users
| Method | Path | Description | Auth required |
|---|
POST | /usuarios | Create a new user account | No |
GET | /usuarios | List all active users | Yes (super-admin) |
PUT | /usuarios/:id | Update a user’s profile and location | Yes |
PUT | /usuarios/eliminado/:id | Soft-delete a user (sets status to inactivo) | Yes |
Equipment
| Method | Path | Description | Auth required |
|---|
POST | /pc | Register a new desktop PC | Yes |
POST | /laptop | Register a new laptop | Yes |
GET | /equipos | List all equipment | Yes |
GET | /equipos/lista | Simplified equipment list for dropdowns | Yes |
GET | /equipos/:id | Get equipment detail by ID | Yes |
PUT | /equipos/:id | Update equipment record | Yes |
GET | /equipo/:id | Get a single equipment document | Yes |
GET | /buscar/:serial | Look up equipment by serial number | Yes |
GET | /verificar-periferico/:dispositivo/:serial | Check whether a serial already exists for a device type | Yes |
GET | /:dispositivo/:id | Get a specific device by type and ID | Yes |
Peripherals
| Method | Path | Description | Auth required |
|---|
POST | /perifericos/:tipo | Register a new peripheral of the given type | Yes |
GET | /componentes | List all peripheral components | Yes |
GET | /perifericos/:id | Get peripheral detail by ID | Yes |
PUT | /perifericos/:tipo/:id | Update a peripheral record | Yes |
Locations
| Method | Path | Description | Auth required |
|---|
GET | /region | List all regions | Yes |
GET | /region/:id/estados | List states belonging to a region | Yes |
GET | /estados/:id/ciudades | List cities belonging to a state | Yes |
GET | /ubicaciones | List all registered locations | Yes |
POST | /ubicaciones | Create a new location | Yes |
GET | /ubicaciones/:id | Get a location by ID | Yes |
PUT | /ubicaciones/:id | Update a location | Yes |
DELETE | /ubicaciones/:id | Permanently delete a location | Yes |
PUT | /ubicaciones/eliminadas/:id | Soft-delete a location | Yes |
Audit Log
| Method | Path | Description | Auth required |
|---|
GET | /bitacora | Retrieve the full audit log | Yes |
Export
| Method | Path | Description | Auth required |
|---|
GET | /export/tipos | List available export formats and report types | Yes |
GET | /export/descargar | Download a report as PDF or Excel | Yes |
Password Recovery
| Method | Path | Description | Auth required |
|---|
POST | /recuperar-password | Send a password-reset email | No |
GET | /validar-token | Validate a password-reset token | No |
POST | /restablecer-password | Set a new password using a valid reset token | No |