Equipment API: Register and Manage PCs and Laptops - Sistema de Inventario Tecnológico

The Equipment API manages the two primary asset types in the inventory — PC and Laptop. Each equipment record embeds an array of internal components (processor, RAM, hard drive, motherboard) and an array of attached peripherals. Every piece of equipment carries two location objects: procedencia (where the asset originated) and asignacion (where it is currently deployed). Serial uniqueness is enforced globally via an indices collection, so the same serial cannot appear in more than one equipment, component, or peripheral record across the entire system.

POST /api/pc

Register a new PC in the inventory. The request is processed inside a Firestore transaction that validates serial uniqueness, normalizes location data, creates the equipment document, and synchronizes any embedded peripherals with the standalone perifericos collection. Auth: Not required.

Request

marca

string

required

Equipment brand (e.g., "HP", "Dell").

modelo

string

required

Equipment model name.

serial

string

required

Unique serial number. Must not already exist in the indices collection.

estado

string

required

Current condition of the equipment (e.g., "Bueno", "Regular", "Dañado").

notas

string

Free-text observations. Stored as null if omitted.

procedencia

object

required

Origin location. Must include region, estado, ciudad, sede, piso. Optionally ala.

asignacion

object

required

Deployment location. Same structure as procedencia.

componentes

array

Array of internal component objects. Each item must include:

tipo (string, required): One of Procesador, Memoria_RAM, Disco_Duro, Motherboard. Partial matches like "ram" or "disco" are auto-mapped.
marca (string): Defaults to "Genérico" if blank.
modelo (string): Defaults to "Genérico" if blank.
serial (string, required): Unique serial for the component.
estado (string, required): Component condition.
capacidad (string): Required when tipo is Memoria_RAM or Disco_Duro.

perifericos

array

Array of peripheral objects. Each item must include:

tipo (string, required): One of Monitor, Teclado, Mouse, Switch, Impresora, Corneta.
marca (string): Defaults to "Genérico" if blank.
modelo (string): Defaults to "Genérico" if blank.
serial (string, required): Unique serial. If the serial already exists in perifericos and is unassigned, the existing document is linked instead of creating a new one.
estado (string, required): Peripheral condition.

Response

message

string

"PC REGISTRADA CON ÉXITO."

string

Firestore document ID of the new equipment record.

Example

curl -X POST http://localhost:3001/api/pc \
  -H "Content-Type: application/json" \
  -d '{
    "marca": "HP",
    "modelo": "ProDesk 400 G7",
    "serial": "MXL1234567",
    "estado": "Bueno",
    "notas": "Adquirido en licitación 2023",
    "procedencia": {
      "region": "Centro Occidental",
      "estado": "Lara",
      "ciudad": "Barquisimeto",
      "sede": "Almacén Central",
      "piso": "1",
      "ala": null
    },
    "asignacion": {
      "region": "Centro Occidental",
      "estado": "Lara",
      "ciudad": "Barquisimeto",
      "sede": "Torre Norte",
      "piso": "3",
      "ala": "A"
    },
    "componentes": [
      {
        "tipo": "Procesador",
        "marca": "Intel",
        "modelo": "Core i5-10500",
        "serial": "PROC-001",
        "estado": "Bueno"
      },
      {
        "tipo": "Memoria_RAM",
        "marca": "Kingston",
        "modelo": "ValueRAM",
        "serial": "RAM-001",
        "estado": "Bueno",
        "capacidad": "8GB"
      },
      {
        "tipo": "Disco_Duro",
        "marca": "Seagate",
        "modelo": "Barracuda",
        "serial": "HDD-001",
        "estado": "Bueno",
        "capacidad": "1TB"
      }
    ],
    "perifericos": [
      {
        "tipo": "Monitor",
        "marca": "LG",
        "modelo": "24MK600M",
        "serial": "MON-001",
        "estado": "Bueno"
      },
      {
        "tipo": "Teclado",
        "marca": "Logitech",
        "modelo": "K120",
        "serial": "TEC-001",
        "estado": "Bueno"
      }
    ]
  }'

POST /api/laptop

Register a new Laptop in the inventory. Identical request shape and behavior as POST /api/pc — the only difference is the stored tipo field is set to "Laptop". Auth: Not required.

Request

Same body fields as POST /api/pc. See above for the full parameter reference.

Response

message

string

"LAPTOP REGISTRADA CON ÉXITO."

string

Firestore document ID of the new laptop record.

Example

curl -X POST http://localhost:3001/api/laptop \
  -H "Content-Type: application/json" \
  -d '{
    "marca": "Lenovo",
    "modelo": "ThinkPad E14",
    "serial": "LNV9876543",
    "estado": "Bueno",
    "procedencia": {
      "region": "Capital",
      "estado": "Distrito Capital",
      "ciudad": "Caracas",
      "sede": "Depósito Sur",
      "piso": "PB"
    },
    "asignacion": {
      "region": "Capital",
      "estado": "Distrito Capital",
      "ciudad": "Caracas",
      "sede": "Oficina Central",
      "piso": "5",
      "ala": "B"
    },
    "componentes": [],
    "perifericos": []
  }'

GET /api/equipos

List all equipment records. Results are scoped by the authenticated user’s sede unless the user holds the Superadministrador role, in which case all records are returned. Supports filtering by type, status, and serial number via query parameters. Auth: Required.

Request

tipo

string

Filter by equipment type. Accepts "PC" or "Laptop" (case-insensitive, normalized internally).

estado

string

Filter by condition (e.g., "Bueno", "Dañado").

serial

string

Filter by exact serial number match (normalized comparison).

Response

Returns a JSON array of full equipment objects. Each element includes:

string

Firestore document ID.

tipo

string

"PC" or "Laptop".

marca

string

Equipment brand.

modelo

string

Equipment model.

serial

string

Serial number.

estado

string

Current condition.

procedencia

object

Origin location object with region, estado, ciudad, sede, piso, ala.

asignacion

object

Deployment location object with the same structure as procedencia.

componentes

array

Array of embedded component objects.

perifericos

array

Array of embedded peripheral objects.

Example

curl "http://localhost:3001/api/equipos?tipo=PC&estado=Bueno" \
  -H "Cookie: acceso_token=<JWT>"

GET /api/equipos/lista

Returns a lightweight list of all equipment suitable for populating dropdowns or selection fields. No authentication required. Auth: Not required.

Request

No parameters.

Response

Returns a JSON array. Each element contains only the identifying fields:

string

Firestore document ID.

serial

string

Serial number.

marca

string

Brand.

modelo

string

Model.

tipo

string

"PC" or "Laptop".

Example

curl http://localhost:3001/api/equipos/lista

GET /api/equipos/:id

Retrieve a single equipment record by its Firestore document ID. Auth: Not required.

Request

string

required

Firestore document ID of the equipment record.

Response

Returns the full equipment document including all embedded componentes and perifericos arrays. Returns 404 if the document does not exist.

Example

curl http://localhost:3001/api/equipos/hJ3kLmN9pQrStU

PUT /api/equipos/:id

Update an existing equipment record. Accepts any combination of top-level fields (marca, modelo, serial, estado, tipo) as well as componentes[] and perifericos[] arrays. Peripheral changes are fully synchronized with the standalone perifericos collection and the indices collection — removed peripherals are unlinked and added peripherals are linked or created as needed. Auth: Not required.

The notas field is not updated by this endpoint. The Firestore update() call does not include notas in its payload, so the existing value is always preserved. To change notas, delete and re-register the equipment.

The componentes array uses a merge strategy: existing components whose serials are present in the new payload are updated in place; components not in the new payload are removed. Send the full desired component list on each request.

Request

string

required

Firestore document ID of the equipment to update.

marca

string

Updated brand.

modelo

string

Updated model.

serial

string

Updated serial number.

estado

string

Updated condition.

tipo

string

Updated type ("PC" or "Laptop").

componentes

array

Full list of component objects to set on the equipment. Omit to leave components unchanged. Each item follows the same structure as in POST /api/pc.

perifericos

array

Full list of peripheral objects to set on the equipment. Peripherals removed from this list are automatically unassigned in their standalone documents.

region

string

Updated deployment region.

estado_ubicacion

string

Updated deployment state (use this field rather than estado when updating location to avoid ambiguity with equipment condition).

ciudad

string

Updated deployment city.

sede

string

Updated deployment office.

piso

string

Updated deployment floor.

alas

string

Updated deployment wing. The source also accepts ala as an alias for the same field.

Response

message

string

"Equipo actualizado correctamente."

string

Firestore document ID of the updated equipment.

Example

curl -X PUT http://localhost:3001/api/equipos/hJ3kLmN9pQrStU \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "Regular",
    "componentes": [
      {
        "tipo": "Procesador",
        "marca": "Intel",
        "modelo": "Core i5-10500",
        "serial": "PROC-001",
        "estado": "Bueno"
      }
    ],
    "perifericos": []
  }'

GET /api/equipo/:id

Alternative single-equipment retrieval endpoint. Guarantees that componentes and perifericos are always arrays (defaulting to [] if the fields are absent in Firestore), making it safe to iterate without a null check on the client. Auth: Not required.

Request

string

required

Firestore document ID of the equipment.

Response

Full equipment document with componentes: [] and perifericos: [] guaranteed. Returns 404 if the document does not exist.

Example

curl http://localhost:3001/api/equipo/hJ3kLmN9pQrStU

GET /api/buscar/:serial

Search for a piece of equipment by its serial number. The comparison is normalized (case-insensitive, accent-insensitive), so "MXL1234567" matches "mxl1234567". Returns the first match found. Auth: Not required.

Request

serial

string

required

Serial number to search for.

Response

Returns the full equipment document on success. Returns 404 with { "message": "Equipo no encontrado" } if no match is found.

Example

curl http://localhost:3001/api/buscar/MXL1234567

GET /api/:dispositivo/:id

Check whether a serial number exists in the global indices collection for a given device type. Returns an array containing { serial } if the serial is found, or an empty array if it is not. This endpoint is used internally to pre-populate form fields and avoid duplicate serial entry. Auth: Not required.

The :id path segment is treated as a serial number, not a Firestore document ID. The route resolves the appropriate index prefix (equipo, periferico, or componente) based on the :dispositivo value and then queries the indices collection. Unrecognized device types fall through to the next middleware (Express next()).

Request

dispositivo

string

required

Device type. Accepted values: equipment types (pc, laptop), peripheral types (monitor, teclado, mouse, switch, impresora, corneta), or component types (procesador, memoria_ram, disco_duro, motherboard). Case-insensitive.

string

required

Serial number to look up.

Response

Returns a JSON array:

[{ "serial": "<value>" }] — the serial is registered in the indices collection.
[] — the serial is not registered.

Example

# Check if a PC serial exists in the indices
curl http://localhost:3001/api/pc/MXL1234567

[{ "serial": "MXL1234567" }]

# Check an unregistered monitor serial
curl http://localhost:3001/api/monitor/MON-UNKNOWN

[]

GET /api/verificar-periferico/:dispositivo/:serial

Check whether a specific peripheral or component serial number is already registered and assigned. Useful for pre-validating a serial before submitting a registration form. Auth: Not required.

Request

dispositivo

string

required

Device type to check. Accepts peripheral types (monitor, teclado, mouse, switch, impresora, corneta) or component types (procesador, memoria_ram, disco_duro, motherboard). Case-insensitive.

serial

string

required

Serial number to look up in the indices collection.

Response

existe

boolean

true if the serial is registered in the system.

asignado

boolean

true if the serial is currently linked to an equipment record.

equipo

string

Type of the linked equipment (e.g., "PC"). Present only when asignado is true.

serialEquipo

string

Serial number of the linked equipment. Present only when asignado is true.

message

string

Human-readable description of the result.

Example

# Check if monitor serial MON-001 is already assigned
curl http://localhost:3001/api/verificar-periferico/monitor/MON-001

{
  "existe": true,
  "asignado": true,
  "equipo": "PC",
  "serialEquipo": "MXL1234567",
  "message": "Este periferico ya está asignado a un equipo (PC) con serial: MXL1234567"
}

Overview

Endpoints

Documentation Index

​POST /api/pc

​Request

​Response

​Example

​POST /api/laptop

​Request

​Response

​Example

​GET /api/equipos

​Request

​Response

​Example

​GET /api/equipos/lista

​Request

​Response

​Example

​GET /api/equipos/:id

​Request

​Response

​Example

​PUT /api/equipos/:id

​Request

​Response

​Example

​GET /api/equipo/:id

​Request

​Response

​Example

​GET /api/buscar/:serial

​Request

​Response

​Example

​GET /api/:dispositivo/:id

​Request

​Response

​Example

​GET /api/verificar-periferico/:dispositivo/:serial

​Request

​Response

​Example

Build docs developers (and LLMs) love

POST /api/pc

Request

Response

Example

POST /api/laptop

Request

Response

Example

GET /api/equipos

Request

Response

Example

GET /api/equipos/lista

Request

Response

Example

GET /api/equipos/:id

Request

Response

Example

PUT /api/equipos/:id

Request

Response

Example

GET /api/equipo/:id

Request

Response

Example

GET /api/buscar/:serial

Request

Response

Example

GET /api/:dispositivo/:id

Request

Response

Example

GET /api/verificar-periferico/:dispositivo/:serial

Request

Response

Example