Peripherals API: Register and Manage Standalone Devices

The Peripherals API manages standalone peripheral devices that exist independently of any particular PC or Laptop. A peripheral can be registered on its own and later linked to an equipment record, or it can be unlinked and returned to a free state. The supported device types are Monitor, Teclado, Mouse, Switch, Impresora, and Corneta. Serial uniqueness is enforced globally — the same serial cannot appear in both the perifericos collection and the indices collection simultaneously.

POST /api/perifericos/:tipo

Register a new standalone peripheral. The :tipo path segment determines the canonical device type stored in Firestore. The request runs inside a Firestore transaction that verifies the serial is not already present in the global indices, reserves it, and creates the peripheral document. Auth: Not required.

If you include a peripheral in the perifericos[] array when registering a PC or Laptop via POST /api/pc or POST /api/laptop, it is automatically created in this collection as well with asignado: true. Use this endpoint only when registering a peripheral that is not yet assigned to any equipment.

Request

tipo

string

required

Device type. Must be one of (case-insensitive): monitor, teclado, mouse, switch, impresora, corneta.

marca

string

Device brand. Defaults to "Genérico" if omitted or blank.

modelo

string

required

Device model name.

serial

string

required

Unique serial number. Rejected if already present in the system indices.

estado

string

required

Device condition (e.g., "Bueno", "Regular", "Dañado").

notas

string

Free-text observations. Stored as null if omitted.

procedencia

object

Origin location. Object with fields region, estado, ciudad, sede, piso, and optionally ala. Stored as null if omitted.

asignacion

object

Current deployment location. Same structure as procedencia. Stored as null if omitted.

Response

message

string

Confirmation including the canonical type name (e.g., "Monitor registrado correctamente.").

string

Firestore document ID of the newly created peripheral.

Example

curl -X POST http://localhost:3001/api/perifericos/monitor \
  -H "Content-Type: application/json" \
  -d '{
    "marca": "Samsung",
    "modelo": "S24F350",
    "serial": "MON-2024-001",
    "estado": "Bueno",
    "notas": "Pantalla Full HD 24 pulgadas",
    "procedencia": {
      "region": "Centro Occidental",
      "estado": "Lara",
      "ciudad": "Barquisimeto",
      "sede": "Almacén Central",
      "piso": "1"
    },
    "asignacion": {
      "region": "Centro Occidental",
      "estado": "Lara",
      "ciudad": "Barquisimeto",
      "sede": "Torre Norte",
      "piso": "2",
      "ala": "A"
    }
  }'

GET /api/componentes

Returns a combined list of all equipment records and all standalone peripherals, each with their flattened deployment location fields. Results are scoped to the authenticated user’s sede unless the user holds the Superadministrador role, in which case all records from all offices are returned. Auth: Required.

Despite the endpoint name, this route returns both full equipment assets (PCs, Laptops) and standalone peripherals — not only internal hardware components. It is the primary data source for the inventory overview table in the frontend.

Request

No request body or query parameters.

Response

Returns a JSON array. Each element represents either an equipment record or a peripheral document:

string

Firestore document ID.

tipo

string

Asset type (e.g., "PC", "Laptop", "Monitor", "Teclado").

marca

string

Brand.

modelo

string

Model.

serial

string

Serial number.

estado

string

Current condition.

region

string | null

Geographic region of the deployment location.

estado_region

string | null

State/province of the deployment location.

ciudad

string | null

City of the deployment location.

sede

string | null

Office building or branch of the deployment location.

piso

string | null

Floor of the deployment location.

ala

string | null

Wing of the deployment location.

Example

curl http://localhost:3001/api/componentes \
  -H "Cookie: acceso_token=<JWT>"

GET /api/perifericos/:id

Retrieve a single peripheral by its Firestore document ID. The response includes an equipoRelacionado field that is resolved by scanning the perifericos[] arrays of all equipment documents in the equipos collection, so the linkage is always current even if it was established indirectly. Auth: Not required.

Request

string

required

Firestore document ID of the peripheral.

Response

string

Firestore document ID.

tipo

string

Canonical device type (e.g., "Monitor").

marca

string

Brand.

modelo

string

Model.

serial

string

Serial number.

estado

string

Condition.

notas

string | null

Observations.

procedencia

object | null

Origin location object.

asignacion

object | null

Deployment location object.

asignado

boolean

true if linked to an equipment record.

equipoId

string | null

Firestore ID of the linked equipment document, or null.

equipoRelacionado

object | null

Summary of the linked equipment: { id, tipo, serial, marca, modelo }, or null if unassigned.

Example

curl http://localhost:3001/api/perifericos/Xp7qRsT2uVwYzA

PUT /api/perifericos/:tipo/:id

Update a peripheral’s metadata, deployment location, and/or equipment assignment. The update is atomic — if a peripheral is moved from one equipment to another, both equipment documents’ perifericos[] arrays are updated in the same Firestore transaction. Auth: Not required.

The procedencia (origin location) field is intentionally never overwritten by this endpoint to protect the historical origin record. Only the asignacion (deployment location) can be changed via the ubicacion field.

Request

tipo

string

required

Device type. Must match one of the allowed types: monitor, teclado, mouse, switch, impresora, corneta (case-insensitive).

string

required

Firestore document ID of the peripheral to update.

marca

string

Updated brand. Keeps existing value if omitted.

modelo

string

Updated model. Keeps existing value if omitted.

serial

string

Updated serial number. If changed, the old index entry is deleted and a new one is created. Rejected if the new serial is already in use.

estado

string

Updated condition.

notas

string

Updated observations.

ubicacion

object

Partial or full deployment location override. Fields provided here are merged over the existing asignacion object.

asignadoA

string

Firestore document ID of the equipment to link this peripheral to. Pass "desvincular" or an empty string "" to unassign the peripheral from its current equipment.

Response

message

string

"Operación realizada con éxito."

string

Firestore document ID of the updated peripheral.

Example

# Reassign a monitor to a different PC
curl -X PUT http://localhost:3001/api/perifericos/monitor/Xp7qRsT2uVwYzA \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "Bueno",
    "asignadoA": "hJ3kLmN9pQrStU"
  }'

# Unassign a monitor
curl -X PUT http://localhost:3001/api/perifericos/monitor/Xp7qRsT2uVwYzA \
  -H "Content-Type: application/json" \
  -d '{
    "asignadoA": "desvincular"
  }'

Overview

Endpoints

POST /api/perifericos/:tipo

Request

Response

Example

GET /api/componentes

Request

Response

Example

GET /api/perifericos/:id

Request

Response

Example

PUT /api/perifericos/:tipo/:id

Request

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/perifericos/:tipo

​Request

​Response

​Example

​GET /api/componentes

​Request

​Response

​Example

​GET /api/perifericos/:id

​Request

​Response

​Example

​PUT /api/perifericos/:tipo/:id

​Request

​Response

​Example

Build docs developers (and LLMs) love

POST /api/perifericos/:tipo

Request

Response

Example

GET /api/componentes

Request

Response

Example

GET /api/perifericos/:id

Request

Response

Example

PUT /api/perifericos/:tipo/:id

Request

Response

Example