Expedientes API — Case File Lifecycle Management - UZDI

The expediente (case file) resource is the operational record that ties an adolescent to their legal infraction, assigned socio-educational measure, and responsible UZDI unit. It tracks the full lifecycle of the measure — from opening date through closure — and exposes the three workflow states enforced by the database CHECK constraint. Case file codes are derived by the frontend as EXP-YYYY-NNNN using the measure start year and the record’s primary key. Base path: /api/v1/expediente

Auto-numbering convention

Case file numbers are not stored in the database. They are computed at read time by the frontend service using the formula:

EXP-{YYYY}-{id padded to 4 digits}

Where YYYY is the four-digit year extracted from fecha_inicio_medida. For example, a record with id = 7 and fecha_inicio_medida = "2024-03-01" renders as EXP-2024-0007.

Estado values

The estado field is constrained to exactly three values, matching a DDL CHECK constraint. Any other value is rejected by the ValidationPipe with a 400 Bad Request.

Value	Badge colour	Meaning
`"En proceso"`	Green	Active — measure is ongoing and compliant.
`"Atraso"`	Amber	Delayed — adolescent is behind scheduled activities.
`"Incomparecencia"`	Red	Non-appearance — adolescent failed to attend.

Role requirements

Operation	Allowed roles
`GET /api/v1/expediente`	`ADMINISTRADOR`, `SUPERADMINISTRADOR`, `TRABAJADOR_SOCIAL`, `PSICOLOGO`, `EDUCADOR`, `JURIDICO`
`GET /api/v1/expediente/:id`	All authenticated users
`POST /api/v1/expediente`	`ADMINISTRADOR`, `SUPERADMINISTRADOR`
`PATCH /api/v1/expediente/:id`	`ADMINISTRADOR`, `SUPERADMINISTRADOR`
`DELETE /api/v1/expediente/:id`	`ADMINISTRADOR`, `SUPERADMINISTRADOR`

A valid JWT must be sent in every request via the Authorization: Bearer <token> header. Obtain a token via POST /api/v1/auth/login.

Endpoints

GET /api/v1/expediente

Returns all case files. Catalogue relations (adolescente, uzdi, infraccion, medida) are resolved eagerly by TypeORM and embedded in each response object.

curl -X GET https://api.uzdi.puce.edu.ec/api/v1/expediente \
  -H "Authorization: Bearer <token>"

Response — 200 OK

Returns an array of Expediente objects.

number

Internal primary key (expe_id in the database).

estado

string

Current workflow state. One of "En proceso", "Atraso", or "Incomparecencia".

fecha_inicio_medida

string (date)

Start date of the socio-educational measure. YYYY-MM-DD format. Used to derive the EXP-YYYY-NNNN display code.

fecha_fin_medida

string (date) | null

Projected or actual end date of the measure. YYYY-MM-DD format. Nullable — omitted until the case is closed or a projected end date is set.

adlc_id

number

Raw foreign key to the adolescente table.

uzdi_id

number

Raw foreign key to the uzdi table.

infc_id

number

Raw foreign key to the infraccion catalogue.

mdso_id

number

Raw foreign key to the medida_socioeducativa catalogue.

adolescente

object

Eagerly resolved adolescent reference. Contains id: number, nombre: string, apellido: string, and cedula: string.

uzdi

object

Eagerly resolved UZDI unit reference. Contains id: number and nombre: string.

infraccion

object

Eagerly resolved infraction type reference. Contains id: number and nombre: string.

medida

object

Eagerly resolved socio-educational measure catalogue reference. Contains id: number and nombre: string.

fcCrea

string (timestamp) | null

Server-set creation timestamp. Not writable via POST or PATCH.

fcMod

string (timestamp) | null

Server-set last-modification timestamp. Not writable via POST or PATCH.

POST /api/v1/expediente

Opens a new case file. All four FK fields must reference valid rows in their respective tables. The estado value is validated against the three allowed strings by @IsIn.

curl -X POST https://api.uzdi.puce.edu.ec/api/v1/expediente \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "adlc_id": 42,
    "uzdi_id": 3,
    "infc_id": 7,
    "mdso_id": 2,
    "estado": "En proceso",
    "fecha_inicio_medida": "2024-03-01"
  }'

Request body

adlc_id

number

required

Foreign key to the adolescent profile (adolescente.adlc_id). Must be an integer referencing an existing record.

uzdi_id

number

required

Foreign key to the responsible UZDI unit. Must be an integer referencing an existing uzdi record.

infc_id

number

required

Foreign key to the infraction type catalogue. Must be an integer referencing an existing infraccion record.

mdso_id

number

required

Foreign key to the socio-educational measure catalogue. Must be an integer referencing an existing medida_socioeducativa record.

estado

string

required

Initial workflow state of the case file. Must be exactly one of "En proceso", "Atraso", or "Incomparecencia". Any other value results in a 400 Bad Request.

fecha_inicio_medida

string

required

Measure start date. Must be a valid ISO 8601 date string, e.g. "2024-03-01". This value is also used by the frontend to compute the EXP-YYYY-NNNN display code.

fecha_fin_medida

string

Projected or actual measure end date. ISO 8601 date string. Optional — may be supplied at creation or set later via PATCH.

Response — 201 Created

Returns the saved Expediente object with the generated id, all eagerly resolved relations, and the server-set fcCrea timestamp. Fields are identical to those described in the GET response above.

The frontend automatically derives the display code EXP-{YYYY}-{id} from the response. This code is not stored in the database and will not appear in the raw API response.

GET /api/v1/expediente/:id

Retrieves a single case file by its numeric primary key.

Path parameter	Type	Description
`id`	`number`	The `expe_id` of the case file to retrieve.

curl -X GET https://api.uzdi.puce.edu.ec/api/v1/expediente/7 \
  -H "Authorization: Bearer <token>"

Response — 200 OK

Returns the matching Expediente object with the same shape as the list response. Returns null if no record is found for the given id.

PATCH /api/v1/expediente/:id

Partially updates an existing case file. Only fields included in the request body are modified. The body is validated by UpdateExpedienteDto — a PartialType of CreateExpedienteDto — so every field is optional but retains all original constraints when present.

Path parameter	Type	Description
`id`	`number`	The `expe_id` of the case file to update.

curl -X PATCH https://api.uzdi.puce.edu.ec/api/v1/expediente/7 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "estado": "Atraso",
    "fecha_fin_medida": "2025-03-01"
  }'

Request body

All fields from the POST body are accepted but every field is optional. Send only the fields you wish to change. The estado field, if included, must still be one of the three allowed values.

Response — 200 OK

Returns a TypeORM UpdateResult with an affected count.

The PATCH endpoint returns a TypeORM UpdateResult, not the full updated entity. Issue a follow-up GET /api/v1/expediente/:id if you need the full updated object with resolved relations.

DELETE /api/v1/expediente/:id

Removes a case file record. At the current scaffolding stage this is a hard DELETE. A soft-close / archive workflow may be introduced in a future iteration.

Path parameter	Type	Description
`id`	`number`	The `expe_id` of the case file to remove.

curl -X DELETE https://api.uzdi.puce.edu.ec/api/v1/expediente/7 \
  -H "Authorization: Bearer <token>"

Response — 200 OK

Returns a TypeORM DeleteResult with an affected count.

Deleting a case file may affect linked documento_expediente records. Ensure all document attachments are removed or archived before calling this endpoint in a production environment.

Authentication

Core Resources

Catalogs & Settings

Expedientes API — Case File Lifecycle Management

Auto-numbering convention

Estado values

Role requirements

Endpoints

GET /api/v1/expediente

Response — 200 OK

POST /api/v1/expediente

Request body

Response — 201 Created

GET /api/v1/expediente/:id

Response — 200 OK

PATCH /api/v1/expediente/:id

Request body

Response — 200 OK

DELETE /api/v1/expediente/:id

Response — 200 OK

Build docs developers (and LLMs) love

Authentication

Core Resources

Catalogs & Settings

Documentation Index

​Auto-numbering convention

​Estado values

​Role requirements

​Endpoints

​GET /api/v1/expediente

​Response — 200 OK

​POST /api/v1/expediente

​Request body

​Response — 201 Created

​GET /api/v1/expediente/:id

​Response — 200 OK

​PATCH /api/v1/expediente/:id

​Request body

​Response — 200 OK

​DELETE /api/v1/expediente/:id

​Response — 200 OK

Build docs developers (and LLMs) love

Auto-numbering convention

Estado values

Role requirements

Endpoints

GET /api/v1/expediente

Response — 200 OK

POST /api/v1/expediente

Request body

Response — 201 Created

GET /api/v1/expediente/:id

Response — 200 OK

PATCH /api/v1/expediente/:id

Request body

Response — 200 OK

DELETE /api/v1/expediente/:id

Response — 200 OK