Search Appeals: Full Mode with Parties and Annexes

The full appeals search module (/api/busquedas) returns complete Apelacion records from the current court system, including nested arrays of parties (partes) and document annexes (anexos). This is the richest projection available and is suited for case review, legal reporting, and export tasks where every relational detail is required. All endpoints in this group require a valid JWT bearer token.

Endpoints overview

Method	Path	Description
`GET`	`/api/busquedas/filtros`	Retrieve filter catalogs (salas, nomenclaturas, tipos de apelación)
`GET`	`/api/busquedas`	Search appeals with filters and pagination
`GET`	`/api/busquedas/exportar-excel`	Export filtered results as an Excel file
`GET`	`/api/busquedas/exportar-pdf`	Export filtered results as a PDF file

GET /api/busquedas/filtros

Returns the catalog values needed to populate search dropdowns on the client — salas, nomenclaturas, and tipos de apelación. No query parameters are required. Authentication: Authorization: Bearer <token>

Response `200`

status

string

required

Always "success" on a successful request.

data

object

required

Catalog arrays used to populate filter dropdowns.

Show data fields

salas

CatalogoBase[]

required

List of available salas (court divisions). Each entry contains id (integer) and nombre (string).

nomenclaturas

CatalogoBase[]

required

List of nomenclatura catalog entries. Each entry contains id (integer) and nombre (string).

apelaciones

CatalogoBase[]

required

List of appeal type catalog entries. Each entry contains id (integer) and nombre (string).

GET /api/busquedas

Searches the Apelacion table and returns a paginated list of full appeal records, each including their associated partes and anexos arrays. Authentication: Authorization: Bearer <token>

At least one search filter (beyond page and limit) must be provided. Requests that supply only pagination parameters — or no parameters at all — will receive a 400 Bad Request response. The server evaluates the filter set using ApelacionFiltrosDTO.tieneFiltros().

Query parameters

page

integer

default:1

Page number for pagination. Starts at 1.

limit

integer

default:10

Number of results per page.

folioOficialia

string

Filter by the internal officialia folio identifier (e.g. "FOL-001"). Partial matches are supported depending on the service implementation.

idSala

integer

Filter by sala ID. Use the catalog values returned by GET /api/busquedas/filtros.

idNomenclatura

integer

Filter by nomenclatura ID. Use the catalog values returned by GET /api/busquedas/filtros.

idApelacion

integer

Filter by appeal type ID. Use the catalog values returned by GET /api/busquedas/filtros.

folioApelacion

string

Filter by the appeal folio (toca number), e.g. "TOCA-2024-001".

expedienteCausa

string

Filter by the originating criminal cause docket number.

nombreParte

string

Filter by party name (defendant, victim, or other participant). The search is applied across the related partes records.

fechaInicio

string (date)

Start of the reception date range. ISO 8601 format: YYYY-MM-DD.

fechaFin

string (date)

End of the reception date range. ISO 8601 format: YYYY-MM-DD.

Response `200`

status

string

required

"success"

message

string

required

Human-readable result message, e.g. "Operación exitosa".

data

object

required

Paginated result envelope.

Show data fields

apelaciones

ApelacionDTO[]

required

Array of full appeal records for the current page. See the ApelacionDTO fields section below.

total

integer

required

Total number of records matching the applied filters across all pages.

page

integer

required

The current page number returned.

limit

integer

required

The page size used for this response.

ApelacionDTO fields

Each object in the apelaciones array has the following structure.

integer

required

Internal primary key of the appeal record.

folioOficialia

string

required

Officialia folio identifier assigned at intake.

folioApelacion

string | null

Appeal folio / toca number assigned after acceptance.

tramite

string

required

Internal processing code.

folioApelacionAnterior

string | null

Previous toca folio if this is a re-filed or related appeal.

folioOficio

string | null

Official correspondence folio number.

fojas

integer | null

Number of pages (fojas) in the dossier.

expedienteAcumulado

string | null

Accumulated docket identifier when multiple cases are joined.

esReposicion

boolean | null

Whether this appeal is a reposition of a prior proceeding.

expedienteCausa

string | null

Originating criminal cause docket number.

fechaAuto

string (date) | null

Date of the judicial auto (ruling). Format: YYYY-MM-DD.

fechaHoraRecepcion

string (date-time) | null

Full timestamp of when the appeal was received. Format: ISO 8601.

fechaHoraIngresoJuz

string (date-time) | null

Full timestamp of when the appeal entered the court system (juzgado intake). Format: ISO 8601.

observaciones

string | null

Free-text observations recorded at intake.

asunto

string | null

Subject matter description of the appeal.

lugarHechos

string | null

Geographic location where the underlying criminal act occurred.

sala

string | null

Name of the sala (court division) currently handling the appeal.

salaAnterior

string | null

Name of the sala that previously handled this case (for reassigned appeals).

juzgado

string | null

Name of the originating trial court (juzgado de origen).

magistrado

string | null

Name of the magistrate assigned to the appeal.

nomenclatura

string | null

Nomenclature classification label.

apelacion

string | null

Appeal type name (descriptive label).

tipoApelacion

string | null

Appeal sub-type classification.

tipoEscrito

string | null

Type of the written submission filed (e.g. "Escrito de apelación").

partes

ParteDTO[]

required

Parties involved in the appeal (defendants, victims, counsel, etc.).

Show ParteDTO fields

nombre

string | null

Full name of the party.

direccion

string | null

Registered address of the party.

menorEdad

boolean | null

Whether the party is a minor.

sexo

string | null

Sex of the party (e.g. "Masculino", "Femenino").

tipoParte

string | null

Role of the party in the proceeding (e.g. "Ofendido", "Imputado").

anexos

AnexoDTO[]

required

Document annexes attached to the appeal.

Show AnexoDTO fields

integer

required

Primary key of the annexe record.

descripcion

string | null

Description of the annexed document.

esValor

boolean | null

Whether the annex has a monetary value.

monto

string | null

Monetary amount if esValor is true.

cantidad

integer | null

Quantity of copies or items.

orden

integer

required

Display order of the annex within the appeal.

idApelacion

integer

required

Foreign key back to the parent appeal.

idAnexo

integer

required

Catalog ID of the annex type.

Error responses

Status	Meaning
`400 Bad Request`	No valid search filters were provided (beyond pagination).
`401 Unauthorized`	Missing or invalid `Authorization` bearer token.

GET /api/busquedas/exportar-excel

Generates and streams a binary Excel workbook (.xlsx) containing all records matching the supplied filters. Pagination parameters are ignored — the export contains the full result set. Authentication: Authorization: Bearer <token>

Use the same filter parameters as the search endpoint. The response includes a Content-Disposition: attachment; filename=apelaciones.xlsx header so browsers will prompt a file download automatically.

Query parameters

Same filter parameters as GET /api/busquedas (excluding page and limit): folioOficialia, idSala, idNomenclatura, idApelacion, folioApelacion, expedienteCausa, nombreParte, fechaInicio, fechaFin.

Response `200`

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=apelaciones.xlsx
Body: Binary Excel file stream.

Error responses

Status	Meaning
`401 Unauthorized`	Missing or invalid `Authorization` bearer token.

GET /api/busquedas/exportar-pdf

Generates and streams a binary PDF document containing all records matching the supplied filters. Authentication: Authorization: Bearer <token>

Query parameters

Same filter parameters as GET /api/busquedas/exportar-excel.

Response `200`

Content-Type: application/pdf
Content-Disposition: attachment; filename=apelaciones.pdf
Body: Binary PDF file stream.

Error responses

Status	Meaning
`401 Unauthorized`	Missing or invalid `Authorization` bearer token.

Examples

Search appeals by sala and date range

curl -G http://localhost:4000/api/busquedas \
  -H 'Authorization: Bearer <token>' \
  --data-urlencode 'idSala=2' \
  --data-urlencode 'fechaInicio=2024-01-01' \
  --data-urlencode 'fechaFin=2024-06-30' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=20'

Search by party name

curl -G http://localhost:4000/api/busquedas \
  -H 'Authorization: Bearer <token>' \
  --data-urlencode 'nombreParte=García López' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10'

Export to Excel

curl -G http://localhost:4000/api/busquedas/exportar-excel \
  -H 'Authorization: Bearer <token>' \
  --data-urlencode 'idSala=2' \
  --data-urlencode 'fechaInicio=2024-01-01' \
  --data-urlencode 'fechaFin=2024-06-30' \
  -o apelaciones.xlsx

Export to PDF

curl -G http://localhost:4000/api/busquedas/exportar-pdf \
  -H 'Authorization: Bearer <token>' \
  --data-urlencode 'folioApelacion=TOCA-2024-001' \
  -o apelaciones.pdf

Authentication

Apelaciones

Búsqueda

Estadísticas

Search Appeals: Full Mode with Parties and Annexes

Endpoints overview

GET /api/busquedas/filtros

Response `200`

GET /api/busquedas

Query parameters

Response `200`

ApelacionDTO fields

Error responses

GET /api/busquedas/exportar-excel

Query parameters

Response `200`

Error responses

GET /api/busquedas/exportar-pdf

Query parameters

Response `200`

Error responses

Examples

Search appeals by sala and date range

Search by party name

Export to Excel

Export to PDF

Build docs developers (and LLMs) love

Authentication

Apelaciones

Búsqueda

Estadísticas

Documentation Index

​Endpoints overview

​GET /api/busquedas/filtros

​Response 200

​GET /api/busquedas

​Query parameters

​Response 200

​ApelacionDTO fields

​Error responses

​GET /api/busquedas/exportar-excel

​Query parameters

​Response 200

​Error responses

​GET /api/busquedas/exportar-pdf

​Query parameters

​Response 200

​Error responses

​Examples

​Search appeals by sala and date range

​Search by party name

​Export to Excel

​Export to PDF

Build docs developers (and LLMs) love

Endpoints overview

GET /api/busquedas/filtros

Response `200`

GET /api/busquedas

Query parameters

Response `200`

ApelacionDTO fields

Error responses

GET /api/busquedas/exportar-excel

Query parameters

Response `200`

Error responses

GET /api/busquedas/exportar-pdf

Query parameters

Response `200`

Error responses

Examples

Search appeals by sala and date range

Search by party name

Export to Excel

Export to PDF