Catalog APIs — Reference Data for Dropdowns and Forms - UZDI

UZDI exposes a set of catalog (lookup table) APIs that supply the reference data used by every form in the application — ethnicity pickers, civil-status dropdowns, kinship selectors, and more. All catalog resources follow the same RESTful shape: an integer primary key and a human-readable nombre field. Mutation endpoints (POST / PATCH / DELETE) are restricted to the Administrador and Superadministrador roles; GET endpoints are available to all authenticated roles. The frontend uses the useCatalogos composable to load every catalog once per browser session, keeping network requests to a minimum.

The `useCatalogos` Composable

UZDI_FRONT/src/composables/useCatalogos.ts

import { ref } from 'vue'
import {
  catalogoService,
  type CatalogoItem,
  type UzdiItem,
  type InfraccionItem,
  type MedidaItem,
} from '../services/catalogo.service'

// Estado global compartido: los catálogos se cargan una sola vez por sesión.
const nacionalidades = ref<CatalogoItem[]>([])
const estadosCiviles = ref<CatalogoItem[]>([])
const etnias = ref<CatalogoItem[]>([])
const gdos = ref<CatalogoItem[]>([])
const cantones = ref<CatalogoItem[]>([])
const uzdis = ref<UzdiItem[]>([])
const infracciones = ref<InfraccionItem[]>([])
const medidas = ref<MedidaItem[]>([])
let cargado = false

export function useCatalogos() {
  async function cargarCatalogos(force = false) {
    if (cargado && !force) return
    const [n, ec, et, g, c, u, i, m] = await Promise.all([
      catalogoService.nacionalidades(),
      catalogoService.estadosCiviles(),
      catalogoService.etnias(),
      catalogoService.gdos(),
      catalogoService.cantones(),
      catalogoService.uzdis(),
      catalogoService.infracciones(),
      catalogoService.medidas(),
    ])
    nacionalidades.value = n
    estadosCiviles.value = ec
    etnias.value = et
    gdos.value = g
    cantones.value = c
    uzdis.value = u
    infracciones.value = i
    medidas.value = m
    cargado = true
  }

  return {
    nacionalidades,
    estadosCiviles,
    etnias,
    gdos,
    cantones,
    uzdis,
    infracciones,
    medidas,
    cargarCatalogos,
  }
}

How it works

State is declared at module scope, so all Vue components that call useCatalogos() share the same reactive refs — there is no duplicate fetching.
cargarCatalogos() fires all eight catalog requests in parallel via Promise.all and sets the cargado flag when they resolve.
On subsequent calls within the same session the early-return guard if (cargado && !force) return exits immediately, making repeated calls to cargarCatalogos() free of cost.
Pass force = true to bust the session cache (e.g. after an admin creates a new catalog entry).
catalogoService (UZDI_FRONT/src/services/catalogo.service.ts) wraps each catalog path with a typed fetchList<T>() helper that silently returns [] on network errors, preventing form crashes.

Catalog Endpoints — Overview

All paths are prefixed with /api/v1. Authentication is required for every request; pass the session JWT in the Authorization: Bearer <token> header.

Resource	Base path	Methods	Description
Etnia	`/api/v1/etnia`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Self-identified ethnic group of an adolescent
Estado Civil	`/api/v1/estado-civil`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Marital / civil status
Nacionalidad	`/api/v1/nacionalidad`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Nationality / country of origin
Tipo Parentesco	`/api/v1/tipo-parentesco`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Kinship type linking a representative to an adolescent
Tipo Documento	`/api/v1/tipo-documento`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Document type for case-file attachments
Taller	`/api/v1/taller`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Workshop / activity definition
Asistencia Taller	`/api/v1/asistencia-taller`	GET · GET /:id · POST · PATCH /:id · DELETE /:id	Workshop attendance record

Read vs. write roles. GET and GET /:id are accessible to all authenticated roles: Administrador, Superadministrador, Trabajador Social, Psicólogo, Educador, and Jurídico. POST, PATCH, and DELETE require the Administrador or Superadministrador role.

Simple Catalogs

The following five resources share an identical structure: a single nombre field alongside the auto-generated primary key and server-managed timestamps. All validation runs through NestJS ValidationPipe (whitelist: true, forbidNonWhitelisted: true) and a global SanitizationPipe (DOMPurify).

Etnia

DB table: adolescente.etnia — primary key column etna_id. Response fields

number

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

nombre

string

Ethnic group name. Max 100 characters.

fcCrea

string | null

ISO-8601 timestamp set automatically by the database on insert.

fcMod

string | null

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

POST / PATCH body

nombre

string

required

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

Estado Civil

DB table: adolescente.estado_civil — primary key column etcv_id. Response fields

number

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

nombre

string

Civil status label (e.g., Soltero/a, Casado/a). Max 100 characters.

fcCrea

string | null

Server-managed creation timestamp.

fcMod

string | null

Server-managed last-modified timestamp.

POST / PATCH body

nombre

string

required

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

Nacionalidad

DB table: adolescente.nacionalidad — primary key column nacn_id. Response fields

number

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

nombre

string

Country or nationality name. Max 100 characters.

fcCrea

string | null

Server-managed creation timestamp.

fcMod

string | null

Server-managed last-modified timestamp.

POST / PATCH body

nombre

string

required

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

Tipo Parentesco

DB table: contexto_familiar.tipo_parentesco — primary key column tprt_id. Response fields

number

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

nombre

string

Kinship type label (e.g., Padre, Madre, Tutor Legal). Max 100 characters.

fcCrea

string | null

Server-managed creation timestamp.

fcMod

string | null

Server-managed last-modified timestamp.

POST / PATCH body

nombre

string

required

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

Tipo Documento

DB table: gestion_documental.tipo_documento — primary key column tpdc_id. This catalog also carries an optional free-text descripcion field. Response fields

number

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

nombre

string

Document type label (e.g., Sentencia Judicial, Informe Psicológico). Max 255 characters.

descripcion

string | null

Optional long description of when this document type is used.

fcCrea

string | null

Server-managed creation timestamp.

fcMod

string | null

Server-managed last-modified timestamp.

POST / PATCH body

nombre

string

required

Document type label. Must be non-empty, 1–255 characters.

descripcion

string

Optional free-text description. No length limit enforced at the DTO layer.

Taller (Workshops)

UZDI_BACK/src/talleres-actividades/taller/taller.controller.ts Workshops are activities assigned as part of socio-educational measures. They live in the talleres_actividades module and follow the same CRUD pattern as the simple catalogs. The entity is currently in scaffold state (fields TBD), but the controller and role guards are fully wired.

Endpoints

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

Path Parameters

number

required

Integer workshop ID. Coerced from the URL string with +id in the controller.

List all workshops — cURL

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

Create a workshop — cURL

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

Update a workshop — cURL

curl -X PATCH "http://localhost:3000/api/v1/taller/3" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "nombre": "Taller de Habilidades Sociales (Actualizado)" }'

Asistencia Taller (Workshop Attendance)

UZDI_BACK/src/talleres-actividades/asistencia-taller/asistencia-taller.controller.ts Attendance records link an adolescent’s representative relationship (adre_id) to a specific workshop session. The FK adre_id references the contexto_familiar.adolescente_representante join table, which models the many-to-many relationship between adolescents and their legal representatives.

Endpoints

Method	Path	Roles	Description
`GET`	`/api/v1/asistencia-taller`	All authenticated	List all attendance records
`GET`	`/api/v1/asistencia-taller/:id`	All authenticated	Retrieve a single attendance record
`POST`	`/api/v1/asistencia-taller`	Administrador, Superadministrador	Register attendance
`PATCH`	`/api/v1/asistencia-taller/:id`	Administrador, Superadministrador	Correct an attendance record
`DELETE`	`/api/v1/asistencia-taller/:id`	Administrador, Superadministrador	Remove an attendance record

Path Parameters

number

required

Integer attendance record ID.

adre_id foreign key. When creating or updating an attendance record, the body must include adre_id — the integer primary key from contexto_familiar.adolescente_representante. This join record is created when a representative is linked to an adolescent and encodes both the adolescent identity and the kinship type. Always resolve a valid adre_id before posting attendance.

List all attendance records — cURL

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

Register attendance — cURL

curl -X POST "http://localhost:3000/api/v1/asistencia-taller" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adre_id": 12,
    "taller_id": 3,
    "fecha": "2025-03-15"
  }'

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

Adding new catalog values. Only users whose tppr_id maps to the Administrador or Superadministrador role may call POST, PATCH, or DELETE on any catalog resource. After creating a new entry, call cargarCatalogos(true) (passing force = true) in the frontend to invalidate the session cache and reload all catalogs.

Authentication

Core Resources

Catalogs & Settings

Catalog APIs — Reference Data for Dropdowns and Forms

The `useCatalogos` Composable

Catalog Endpoints — Overview

Simple Catalogs

Etnia

Estado Civil

Nacionalidad

Tipo Parentesco

Tipo Documento

Taller (Workshops)

Endpoints

Path Parameters

List all workshops — cURL

Create a workshop — cURL

Update a workshop — cURL

Asistencia Taller (Workshop Attendance)

Endpoints

Path Parameters

List all attendance records — cURL

Register attendance — cURL

Role Reference

Build docs developers (and LLMs) love

Authentication

Core Resources

Catalogs & Settings

Documentation Index

​The useCatalogos Composable

​Catalog Endpoints — Overview

​Simple Catalogs

​Etnia

​Estado Civil

​Nacionalidad

​Tipo Parentesco

​Tipo Documento

​Taller (Workshops)

​Endpoints

​Path Parameters

​List all workshops — cURL

​Create a workshop — cURL

​Update a workshop — cURL

​Asistencia Taller (Workshop Attendance)

​Endpoints

​Path Parameters

​List all attendance records — cURL

​Register attendance — cURL

​Role Reference

Build docs developers (and LLMs) love

The `useCatalogos` Composable

Catalog Endpoints — Overview

Simple Catalogs

Etnia

Estado Civil

Nacionalidad

Tipo Parentesco

Tipo Documento

Taller (Workshops)

Endpoints

Path Parameters

List all workshops — cURL

Create a workshop — cURL

Update a workshop — cURL

Asistencia Taller (Workshop Attendance)

Endpoints

Path Parameters

List all attendance records — cURL

Register attendance — cURL

Role Reference