> ## Documentation Index
> Fetch the complete documentation index at: https://a3erpapi.appcloud.es/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginación, filtrado y ordenación en la A3ERP API REST

> Aprende a paginar resultados, aplicar filtros SQL y ordenar datos en cualquier endpoint de consulta de la A3ERP API usando cabeceras HTTP.

La A3ERP API ofrece mecanismos para controlar la cantidad y el orden de los datos que recibes en cada consulta. Puedes contar registros, paginar resultados, ordenarlos por cualquier columna y filtrarlos mediante condiciones SQL. Todos estos mecanismos se aplican usando **cabeceras HTTP** o **parámetros en la URL**.

***

## 1. Contar registros

Antes de paginar, es habitual querer saber cuántos registros tiene un endpoint. Para ello, añade la cabecera `contar: T` a cualquier petición `GET`:

```http theme={null}
GET /api/{endpoint} HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer {JWT Token}
contar: T
```

**Ejemplo con curl:**

```bash theme={null}
curl -X GET https://<domain>:<port>/api/clientes \
  -H "Authorization: Bearer {JWT Token}" \
  -H "contar: T"
```

**Respuesta:**

```json theme={null}
[
  {
    "registros": 1
  }
]
```

<Note>
  El parámetro `contar` **no es compatible** con la paginación (`Page` / `PageSize`). Úsalos por separado: primero cuenta los registros para saber cuántas páginas necesitas, luego pagina para obtenerlos.
</Note>

***

## 2. Paginación

Para paginar los resultados de un endpoint, usa las cabeceras `Page` y `PageSize` junto con la ruta de ordenación `/order/{columna} {asc|desc}`. La paginación **requiere obligatoriamente** un criterio de ordenación para garantizar resultados consistentes.

**URL con ordenación:**

```
GET /api/{endpoint}/order/{columna} {asc|desc}
```

**Cabeceras necesarias:**

| Cabecera   | Tipo      | Descripción                                  |
| ---------- | --------- | -------------------------------------------- |
| `Page`     | `integer` | Número de página a devolver. Empieza en `1`. |
| `PageSize` | `integer` | Número máximo de registros por página.       |

**Ejemplo — segunda página de clientes, 50 por página, ordenados por nombre:**

```bash theme={null}
curl -X GET "https://<domain>:<port>/api/clientes/order/nomcli asc" \
  -H "Authorization: Bearer {JWT Token}" \
  -H "Page: 2" \
  -H "PageSize: 50"
```

En formato HTTP:

```http theme={null}
GET /api/clientes/order/nomcli asc HTTP/1.1
Host: <domain>:<port>
Authorization: Bearer {JWT Token}
Page: 2
PageSize: 50
Accept: */*
```

**Respuesta:**

```json theme={null}
[
  {
    "codcli": "000001",
    "nomcli": "ACME, S.L.",
    "...": "..."
  },
  {
    "codcli": "000002",
    "nomcli": "BETA CORP, S.A.",
    "...": "..."
  }
]
```

***

## 3. Ordenación

Si solo quieres ordenar sin paginar, puedes usar la ruta `/order/{campo}` sin las cabeceras `Page` y `PageSize`:

```bash theme={null}
curl -X GET "https://<domain>:<port>/api/articulos/order/desart desc" \
  -H "Authorization: Bearer {JWT Token}"
```

Los valores posibles para el orden son:

| Valor  | Descripción                       |
| ------ | --------------------------------- |
| `asc`  | Orden ascendente (A → Z, 0 → 9).  |
| `desc` | Orden descendente (Z → A, 9 → 0). |

***

## 4. Filtrado SQL

Puedes filtrar los resultados de cualquier endpoint añadiendo `/filtro/{filtro}` a la URL. El parámetro `filtro` es una **condición SQL tipo WHERE** que se aplica sobre los resultados.

**Formato:**

```
GET /api/{endpoint}/filtro/{condicion_sql}
```

**Ejemplo — órdenes de producción del cliente SPORTIF, S.A.:**

```bash theme={null}
curl -X GET "https://<domain>:<port>/api/ordenproduccion/filtro/nomcli='SPORTIF, S.A.'" \
  -H "Authorization: Bearer {JWT Token}"
```

**Ejemplo — facturas con importe superior a 1000:**

```bash theme={null}
curl -X GET "https://<domain>:<port>/api/facturas/filtro/impfac>1000" \
  -H "Authorization: Bearer {JWT Token}"
```

<Warning>
  El filtro es una condición SQL que se ejecuta directamente en la base de datos. **Nunca uses como filtro datos introducidos directamente por el usuario final sin validarlos o escaparlos previamente**, ya que podrías exponerte a inyección SQL. Construye siempre los filtros en el lado del servidor con parámetros controlados.
</Warning>

***

## 5. Combinar filtro y ordenación

Puedes combinar el filtrado y la ordenación en la misma llamada:

```bash theme={null}
curl -X GET "https://<domain>:<port>/api/clientes/filtro/provinci='BARCELONA'/order/nomcli asc" \
  -H "Authorization: Bearer {JWT Token}" \
  -H "Page: 1" \
  -H "PageSize: 25"
```

***

## Resumen de parámetros

| Mecanismo        | Dónde se aplica                              | Ejemplo                   |
| ---------------- | -------------------------------------------- | ------------------------- |
| Contar registros | Cabecera `contar: T`                         | `contar: T`               |
| Paginación       | Cabeceras `Page` y `PageSize` + ruta `order` | `Page: 1`, `PageSize: 50` |
| Ordenación       | Ruta `/order/{campo} {asc\|desc}`            | `/order/nomcli asc`       |
| Filtrado         | Ruta `/filtro/{condicion_sql}`               | `/filtro/nomcli='ACME'`   |