Institutional Structure API — Provinces, Cantons, UZDI - UZDI

Ecuador’s territory is organised into provinces, each subdivided into cantons. Every UZDI (Unidad de Sustentabilidad y Desarrollo Integral) office is anchored to a specific canton, creating a three-level geographic hierarchy that drives the organisational structure of the entire system.

Provincia  (province)
  └── Canton  (canton / municipality)
        └── UZDI  (office)
              └── User (prsn.uzdi_id → uzdi.uzdi_id)

Each system user (seguridad.prsn) carries a uzdi_id foreign key that assigns them to one UZDI office. This determines their data scope — dashboards, adolescent lists, and reports are all filtered by the user’s assigned UZDI. All paths are prefixed with /api/v1. A valid JWT must be supplied as Authorization: Bearer <token> on every request. Mutation endpoints (POST / PATCH / DELETE) require the Administrador or Superadministrador role; GET endpoints are open to all authenticated roles.

Geographic Hierarchy

┌──────────────────────────────────┐
│           Provincia              │
│  prov_id  │  nombre              │
└──────────────┬───────────────────┘
               │  1 : N
┌──────────────▼───────────────────┐
│             Canton               │
│  cntn_id  │  prov_id  │  nombre  │
└──────────────┬───────────────────┘
               │  1 : N
┌──────────────▼────────────────────────────────────────────────────┐
│                            UZDI                                   │
│  uzdi_id │ cntn_id │ nombre │ zona │ direccion │ telefono │ correo │
└──────────────┬────────────────────────────────────────────────────┘
               │  1 : N
┌──────────────▼───────────────────┐
│       User (seguridad.prsn)      │
│  prsn_id  │  uzdi_id  │  ...     │
└──────────────────────────────────┘

UZDI Offices

UZDI_BACK/src/estructura-institucional/uzdi/uzdi.controller.ts UZDI offices are the organisational root of the system. The ParametrosView in the frontend calls uzdiService.getById() and uzdiService.update() to display and edit the active office’s configuration.

Endpoints

Method	Path	Roles	Description
`GET`	`/api/v1/uzdi`	All authenticated	List all UZDI offices
`GET`	`/api/v1/uzdi/:id`	All authenticated	Retrieve a single UZDI office
`POST`	`/api/v1/uzdi`	Administrador, Superadministrador	Create a new UZDI office
`PATCH`	`/api/v1/uzdi/:id`	Administrador, Superadministrador	Update office details
`DELETE`	`/api/v1/uzdi/:id`	Administrador, Superadministrador	Remove a UZDI office

Path Parameters

number

required

Integer UZDI office ID (uzdi_id in the database). Coerced with +id in the controller.

UZDI Entity Fields

DB table: estructura_institucional.uzdi — primary key column uzdi_id.

number

Auto-incremented primary key (uzdi_id in the database).

cntn_id

number

Foreign key referencing estructura_institucional.canton.cntn_id. Determines which canton this office belongs to.

nombre

string

Full name of the UZDI office. Max 255 characters.

zona

string

Administrative zone label (e.g., Zona 1 — Norte). Max 100 characters.

direccion

string | null

Street address of the office. Max 255 characters. Optional.

telefono

string | null

Contact phone number. Max 20 characters. Optional.

correo

string | null

Institutional email address. Max 100 characters. Optional.

fcCrea

string | null

ISO-8601 timestamp set automatically by the database on insert. Read-only; not accepted in POST/PATCH bodies.

fcMod

string | null

ISO-8601 timestamp updated automatically by the database on every change. Read-only.

POST / PATCH Body

cntn_id

number

required

Integer canton ID. Must reference an existing record in estructura_institucional.canton.

nombre

string

required

Office name. Must be non-empty, 1–255 characters.

zona

string

required

Zone label. Must be non-empty, 1–100 characters.

direccion

string

Street address. Optional. Max 255 characters.

telefono

string

Contact phone number. Optional. Max 20 characters.

correo

string

Institutional email. Optional. Max 100 characters.

List all UZDI offices — cURL

curl -X GET "http://localhost:3000/api/v1/uzdi" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example response

[
  {
    "id": 1,
    "cntn_id": 5,
    "nombre": "UZDI Quito Norte",
    "zona": "Zona 2 — Centro Norte",
    "direccion": "Av. América N32-140 y Mariana de Jesús",
    "telefono": "022-345678",
    "correo": "[email protected]",
    "fcCrea": "2024-01-15T08:00:00.000Z",
    "fcMod": "2025-02-10T14:23:00.000Z"
  }
]

Get one UZDI office — cURL

curl -X GET "http://localhost:3000/api/v1/uzdi/1" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Update a UZDI office — cURL

curl -X PATCH "http://localhost:3000/api/v1/uzdi/1" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "telefono": "022-999000",
    "correo": "[email protected]"
  }'

Create a UZDI office — cURL

curl -X POST "http://localhost:3000/api/v1/uzdi" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cntn_id": 8,
    "nombre": "UZDI Cuenca",
    "zona": "Zona 6 — Austro",
    "direccion": "Calle Larga 1-23 y Tomás Ordóñez",
    "telefono": "074-123456",
    "correo": "[email protected]"
  }'

Frontend integration — ParametrosView. The uzdiService (UZDI_FRONT/src/services/uzdi.service.ts) exposes exactly two methods: getById(id) and update(id, payload), which map to GET /api/v1/uzdi/:id and PATCH /api/v1/uzdi/:id respectively. The ParametrosView reads the current user’s uzdi_id from the auth store and calls getById on mount to populate the Organización section; saving calls update with a partial UzdiDto.

Provincias (Provinces)

UZDI_BACK/src/estructura-institucional/provincia/provincia.controller.ts Provinces are the top tier of the geographic hierarchy. In practice, province records are seeded from Ecuador’s official 24 provinces and rarely change; mutation endpoints exist for administrative completeness.

Endpoints

Method	Path	Roles	Description
`GET`	`/api/v1/provincia`	All authenticated	List all provinces
`GET`	`/api/v1/provincia/:id`	All authenticated	Retrieve a single province
`POST`	`/api/v1/provincia`	Administrador, Superadministrador	Create a province
`PATCH`	`/api/v1/provincia/:id`	Administrador, Superadministrador	Update a province
`DELETE`	`/api/v1/provincia/:id`	Administrador, Superadministrador	Remove a province

Path Parameters

number

required

Integer province ID (prov_id in the database).

Provincia Entity Fields

DB table: estructura_institucional.provincia — primary key column prov_id.

number

Auto-incremented primary key (prov_id in the database).

nombre

string

Province name (e.g., Pichincha, Guayas). Max 100 characters.

fcCrea

string | null

Server-managed creation timestamp. Read-only.

fcMod

string | null

Server-managed last-modified timestamp. Read-only.

POST / PATCH Body

nombre

string

required

Province name. Must be non-empty, 1–100 characters.

List all provinces — cURL

curl -X GET "http://localhost:3000/api/v1/provincia" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example response

[
  { "id": 1, "nombre": "Azuay",      "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null },
  { "id": 2, "nombre": "Bolívar",    "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null },
  { "id": 3, "nombre": "Cañar",      "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null },
  { "id": 17, "nombre": "Pichincha", "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null }
]

Create a province — cURL

curl -X POST "http://localhost:3000/api/v1/provincia" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "nombre": "Pichincha" }'

Cantones (Cantons)

UZDI_BACK/src/estructura-institucional/canton/canton.controller.ts Cantons are the second tier of the hierarchy, each belonging to exactly one province via the prov_id foreign key. Cantons are used to group UZDI offices geographically and also populate the canton dropdown in the AdolescenteForm.

Endpoints

Method	Path	Roles	Description
`GET`	`/api/v1/canton`	All authenticated	List all cantons
`GET`	`/api/v1/canton/:id`	All authenticated	Retrieve a single canton
`POST`	`/api/v1/canton`	Administrador, Superadministrador	Create a canton
`PATCH`	`/api/v1/canton/:id`	Administrador, Superadministrador	Update a canton
`DELETE`	`/api/v1/canton/:id`	Administrador, Superadministrador	Remove a canton

Path Parameters

number

required

Integer canton ID (cntn_id in the database).

Canton Entity Fields

DB table: estructura_institucional.canton — primary key column cntn_id.

number

Auto-incremented primary key (cntn_id in the database).

prov_id

number

Foreign key referencing estructura_institucional.provincia.prov_id.

nombre

string

Canton name (e.g., Quito, Guayaquil, Cuenca). Max 100 characters.

fcCrea

string | null

Server-managed creation timestamp. Read-only.

fcMod

string | null

Server-managed last-modified timestamp. Read-only.

POST / PATCH Body

prov_id

number

required

Integer province ID. Must reference an existing record in estructura_institucional.provincia.

nombre

string

required

Canton name. Must be non-empty, 1–100 characters.

List all cantons — cURL

curl -X GET "http://localhost:3000/api/v1/canton" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Example response

[
  { "id": 1,  "prov_id": 17, "nombre": "Quito",     "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null },
  { "id": 2,  "prov_id": 17, "nombre": "Cayambe",   "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null },
  { "id": 25, "prov_id": 9,  "nombre": "Guayaquil", "fcCrea": "2024-01-01T00:00:00.000Z", "fcMod": null }
]

Create a canton — cURL

curl -X POST "http://localhost:3000/api/v1/canton" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prov_id": 17,
    "nombre": "Pedro Moncayo"
  }'

Update a canton — cURL

curl -X PATCH "http://localhost:3000/api/v1/canton/42" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "nombre": "Pedro Vicente Maldonado" }'

UZDI as Organisational Root

Every user record in seguridad.prsn carries a uzdi_id column that determines which office the user belongs to. This FK is set at user creation time (via POST /api/v1/users) and used by the backend to scope data access. The useCatalogos composable loads the full list of UZDI offices at session start so that admin forms can present an office picker without an extra round-trip.

Cascading deletes are not configured. Deleting a UZDI office that still has associated users, adolescents, or attendance records will produce a foreign-key constraint violation at the database level. Always reassign or archive dependent records before removing geographic hierarchy entries.

Role Reference

Role constant	Display name
`Rol.ADMINISTRADOR`	Administrador
`Rol.SUPERADMINISTRADOR`	Superadministrador
`Rol.TRABAJADOR_SOCIAL`	Trabajador Social
`Rol.PSICOLOGO`	Psicólogo
`Rol.EDUCADOR`	Educador
`Rol.JURIDICO`	Jurídico

Authentication

Core Resources

Catalogs & Settings

Institutional Structure API — Provinces, Cantons, UZDI

Geographic Hierarchy

UZDI Offices

Endpoints

Path Parameters

UZDI Entity Fields

POST / PATCH Body

List all UZDI offices — cURL

Get one UZDI office — cURL

Update a UZDI office — cURL

Create a UZDI office — cURL

Provincias (Provinces)

Endpoints

Path Parameters

Provincia Entity Fields

POST / PATCH Body

List all provinces — cURL

Create a province — cURL

Cantones (Cantons)

Endpoints

Path Parameters

Canton Entity Fields

POST / PATCH Body

List all cantons — cURL

Create a canton — cURL

Update a canton — cURL

UZDI as Organisational Root

Role Reference

Build docs developers (and LLMs) love

Authentication

Core Resources

Catalogs & Settings

Documentation Index

​Geographic Hierarchy

​UZDI Offices

​Endpoints

​Path Parameters

​UZDI Entity Fields

​POST / PATCH Body

​List all UZDI offices — cURL

​Get one UZDI office — cURL

​Update a UZDI office — cURL

​Create a UZDI office — cURL

​Provincias (Provinces)

​Endpoints

​Path Parameters

​Provincia Entity Fields

​POST / PATCH Body

​List all provinces — cURL

​Create a province — cURL

​Cantones (Cantons)

​Endpoints

​Path Parameters

​Canton Entity Fields

​POST / PATCH Body

​List all cantons — cURL

​Create a canton — cURL

​Update a canton — cURL

​UZDI as Organisational Root

​Role Reference

Build docs developers (and LLMs) love

Geographic Hierarchy

UZDI Offices

Endpoints

Path Parameters

UZDI Entity Fields

POST / PATCH Body

List all UZDI offices — cURL

Get one UZDI office — cURL

Update a UZDI office — cURL

Create a UZDI office — cURL

Provincias (Provinces)

Endpoints

Path Parameters

Provincia Entity Fields

POST / PATCH Body

List all provinces — cURL

Create a province — cURL

Cantones (Cantons)

Endpoints

Path Parameters

Canton Entity Fields

POST / PATCH Body

List all cantons — cURL

Create a canton — cURL

Update a canton — cURL

UZDI as Organisational Root

Role Reference