Locations API: Regions, States, Cities, and Offices

The Locations API serves two complementary purposes. The first group of endpoints exposes the geographic hierarchy — regions, states, and cities — stored in Firestore as reference collections (regiones, estados, ciudades). These are read-only lookups used to populate cascading dropdowns in the UI. The second group manages ubicaciones — the concrete office locations (building, floor, wing) that are attached to users, equipment, and peripherals throughout the system. Every location is identified by a deterministic, content-derived document ID (ubi_<sha1>) computed from its normalized field values. This means identical locations always map to the same document, preventing duplicates and enabling direct lookups without queries.

GET /api/region

List all available geographic regions ordered alphabetically by name. Auth: Not required.

Request

No parameters.

Response

Returns a JSON array:

id_region

string

Firestore document ID (used as the id argument in GET /api/region/:id/estados).

nombre

string

Human-readable region name (e.g., "Centro Occidental").

Example

curl http://localhost:3001/api/region

[
  { "id_region": "Capital", "nombre": "Capital" },
  { "id_region": "Centro Occidental", "nombre": "Centro Occidental" },
  { "id_region": "Zuliana", "nombre": "Zuliana" }
]

GET /api/region/:id/estados

List all states that belong to a specific region, ordered alphabetically. Auth: Not required.

Request

string

required

Region ID as returned by GET /api/region (the id_region field).

Response

Returns a JSON array:

id_estado

string

Firestore document ID (used as the id argument in GET /api/estados/:id/ciudades).

nombre

string

State name (e.g., "Lara").

Example

curl http://localhost:3001/api/region/Centro%20Occidental/estados

[
  { "id_estado": "Lara", "nombre": "Lara" },
  { "id_estado": "Portuguesa", "nombre": "Portuguesa" }
]

GET /api/estados/:id/ciudades

List all cities within a specific state, ordered alphabetically. Auth: Not required.

Request

string

required

State ID as returned by GET /api/region/:id/estados (the id_estado field).

Response

Returns a JSON array:

id_ciudad

string

Firestore document ID.

nombre

string

City name (e.g., "Barquisimeto").

Example

curl http://localhost:3001/api/estados/Lara/ciudades

[
  { "id_ciudad": "Barquisimeto", "nombre": "Barquisimeto" },
  { "id_ciudad": "Cabudare", "nombre": "Cabudare" }
]

GET /api/ubicaciones

List all active office locations (status: "Activo"). The result is deduplicated by the combination of region | estado | ciudad | sede | piso | ala, so if the same logical location was created multiple times it appears only once. Results are sorted by sede + piso. Auth: Not required.

Request

No parameters.

Response

Returns a JSON array. Each element is a full location object:

string

Deterministic Firestore document ID (format: ubi_<sha1hash>).

region

string

Geographic region.

estado

string

State/province.

ciudad

string

City.

sede

string

Office building or branch name.

piso

string

Floor number or label.

ala

string | null

Wing or section. null if not applicable.

status

string

Always "Activo" in this endpoint’s results.

createdAt

string

Firestore server timestamp of when the document was first created.

Example

curl http://localhost:3001/api/ubicaciones

[
  {
    "id": "ubi_a3f9c12b...",
    "region": "Centro Occidental",
    "estado": "Lara",
    "ciudad": "Barquisimeto",
    "sede": "Torre Norte",
    "piso": "3",
    "ala": "A",
    "status": "Activo",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

POST /api/ubicaciones

Create a new office location. The document ID is derived deterministically from the normalized field values. Returns 409 Conflict if a location with the same data already exists. Auth: Required. Role: write permission (enforced by permitirEscritura middleware).

Request

region

string

required

Geographic region name.

estado

string

required

State/province name.

ciudad

string

required

City name.

sede

string

required

Office building or branch name.

piso

string

required

Floor number or label.

ala

string

Wing or section. Optional — stored as null if omitted.

Response

message

string

"Ubicación registrada con éxito"

string

The deterministic document ID assigned to the new location.

region

string

Normalized region stored in Firestore.

estado

string

Normalized state stored in Firestore.

ciudad

string

Normalized city stored in Firestore.

sede

string

Normalized sede stored in Firestore.

piso

string

Normalized floor stored in Firestore.

ala

string | null

Normalized wing stored in Firestore.

Example

curl -X POST http://localhost:3001/api/ubicaciones \
  -H "Content-Type: application/json" \
  -H "Cookie: acceso_token=<JWT>" \
  -d '{
    "region": "Centro Occidental",
    "estado": "Lara",
    "ciudad": "Barquisimeto",
    "sede": "Torre Sur",
    "piso": "2",
    "ala": "B"
  }'

GET /api/ubicaciones/:id

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

Request

string

required

Firestore document ID (the ubi_<sha1> string returned by create or list operations).

Response

Full location document. Returns 404 if the document does not exist.

Example

curl http://localhost:3001/api/ubicaciones/ubi_a3f9c12b

PUT /api/ubicaciones/:id

Update an existing location. If the normalized field values remain unchanged, the existing document is updated in place. If the values produce a different document ID (meaning the location identity changed), the old document is deleted and a new one is created atomically inside a Firestore transaction. Returns 409 if the new ID already exists. Auth: Required. Role: write permission.

Changing a location’s identity (which causes the document ID to change) does not automatically cascade to all users, equipment, and peripheral documents that reference the old location. Any such cascade must be handled separately at the application level.

Request

string

required

Current Firestore document ID of the location.

region

string

required

Updated region.

estado

string

required

Updated state.

ciudad

string

required

Updated city.

sede

string

required

Updated office building.

piso

string

required

Updated floor.

ala

string

Updated wing. Pass null to clear.

Response

message

string

"Ubicación actualizada con éxito"

string

The document ID after the update (may differ from the request :id if the identity changed).

Example

curl -X PUT http://localhost:3001/api/ubicaciones/ubi_a3f9c12b \
  -H "Content-Type: application/json" \
  -H "Cookie: acceso_token=<JWT>" \
  -d '{
    "region": "Centro Occidental",
    "estado": "Lara",
    "ciudad": "Barquisimeto",
    "sede": "Torre Sur",
    "piso": "3",
    "ala": "B"
  }'

DELETE /api/ubicaciones/:id

Permanently delete a location document from Firestore. This operation is irreversible. Auth: Required. Role: write permission.

This is a hard delete. The document is removed from Firestore immediately with no soft-delete flag. Prefer PUT /api/ubicaciones/eliminadas/:id if you need to preserve the record for audit purposes.

Request

string

required

Firestore document ID of the location to delete.

Response

message

string

"Ubicación eliminada con éxito"

Example

curl -X DELETE http://localhost:3001/api/ubicaciones/ubi_a3f9c12b \
  -H "Cookie: acceso_token=<JWT>"

PUT /api/ubicaciones/eliminadas/:id

Soft-delete a location by setting its status field to "inactivo". The document is retained in Firestore and excluded from the GET /api/ubicaciones listing (which filters by status == "Activo"). A "Eliminar ubicación" entry is written to the bitácora. Auth: Required.

Use this endpoint in preference to DELETE /api/ubicaciones/:id when you need to preserve the location record for historical reference while preventing it from being selected in the UI.

Request

string

required

Firestore document ID of the location to deactivate.

Response

message

string

"Ubicación eliminada (lógicamente)."

Example

curl -X PUT http://localhost:3001/api/ubicaciones/eliminadas/ubi_a3f9c12b \
  -H "Cookie: acceso_token=<JWT>"

Overview

Endpoints

GET /api/region

Request

Response

Example

GET /api/region/:id/estados

Request

Response

Example

GET /api/estados/:id/ciudades

Request

Response

Example

GET /api/ubicaciones

Request

Response

Example

POST /api/ubicaciones

Request

Response

Example

GET /api/ubicaciones/:id

Request

Response

Example

PUT /api/ubicaciones/:id

Request

Response

Example

DELETE /api/ubicaciones/:id

Request

Response

Example

PUT /api/ubicaciones/eliminadas/:id

Request

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/region

​Request

​Response

​Example

​GET /api/region/:id/estados

​Request

​Response

​Example

​GET /api/estados/:id/ciudades

​Request

​Response

​Example

​GET /api/ubicaciones

​Request

​Response

​Example

​POST /api/ubicaciones

​Request

​Response

​Example

​GET /api/ubicaciones/:id

​Request

​Response

​Example

​PUT /api/ubicaciones/:id

​Request

​Response

​Example

​DELETE /api/ubicaciones/:id

​Request

​Response

​Example

​PUT /api/ubicaciones/eliminadas/:id

​Request

​Response

​Example

Build docs developers (and LLMs) love

GET /api/region

Request

Response

Example

GET /api/region/:id/estados

Request

Response

Example

GET /api/estados/:id/ciudades

Request

Response

Example

GET /api/ubicaciones

Request

Response

Example

POST /api/ubicaciones

Request

Response

Example

GET /api/ubicaciones/:id

Request

Response

Example

PUT /api/ubicaciones/:id

Request

Response

Example

DELETE /api/ubicaciones/:id

Request

Response

Example

PUT /api/ubicaciones/eliminadas/:id

Request

Response

Example