---
title: 'Parámetros de listado'
description: 'Filtra, ordena y pagina cualquier endpoint de listado con la sintaxis q[]/o[]/e/p.'
---

# Parámetros de listado

Cada endpoint de listado en la API de Guper entiende una gramática de querystring compartida para filtrado, ordenamiento y paginación. Una vez que la conoces para un recurso, funciona igual en todos los demás.

> **¿`q[]` o QON?** Esta es la gramática `q[]`, para **leer y listar**: buscar un cliente, filtrar pedidos, paginar un reporte. [QON](/docs/{lang}/api-reference/register/audience-query/qon-query) es otra cosa — expresiones anidadas en JSON que sirven **solo para armar audiencia** en el constructor de segmentación. Para encontrar un cliente por RFC/documento o correo, es `q[]`, aquí — no QON.

## Filtrado — `q[columna][operador]=valor`

```
q[columna][operador]=valor
```

- **`columna`** — puede ser compuesta, separada por `;` o `|`.
- **`operador`** — uno de:

| Operador | Significado | Equivalente SQL |
|---|---|---|
| `E` | igual | `=` |
| `!E` | distinto | `!=` |
| `B` | anterior | `<` |
| `BE` | anterior o igual | `<=` |
| `A` | posterior | `>` |
| `AE` | posterior o igual | `>=` |
| `IS` | es | `IS NULL` |
| `!IS` | no es | `IS NOT NULL` |
| `IN` | dentro del conjunto | `IN (1, 2, …)` |
| `!IN` | fuera del conjunto | `NOT IN (1, 2, …)` |
| `L` | like | `LIKE "valor"` |
| `!L` | not like | `NOT LIKE "valor"` |
| `LL` | left-like | `LIKE "%valor"` |
| `!LL` | not left-like | `NOT LIKE "%valor"` |
| `RL` | right-like | `LIKE "valor%"` |
| `!RL` | not right-like | `NOT LIKE "valor%"` |
| `LRL` | left+right like | `LIKE "%valor%"` |
| `!LRL` | not left+right like | `NOT LIKE "%valor%"` |
| `S` | búsqueda | búsqueda por término en una o más columnas |

### Múltiples valores

Los operadores que aceptan múltiples valores deben configurarse en secuencia:

```
q[columna][IN]=1&q[columna][]=2&q[columna][]=3
```

Genera `columna IN (1, 2, 3)`.

### Filtro NULL

```
q[columna][IS]=null
```

## Ordenamiento — `o[columna]=dir`

```
o[columna]=dir
```

- **`columna`** — columna por la cual ordenar.
- **`dir`** — `ASC` / `asc` / `1` para ascendente, `DESC` / `desc` / `0` para descendente.

## Paginación — `e=entries&p=page`

| Parámetro | Default | Notas |
|---|---|---|
| `e` (entries) | `20` | Items por página. Máximo `1000`. `0` significa sin límite. |
| `p` (page) | `1` | Mínimo `1`. |

## Ejemplos

### Rango de fechas

La misma columna acepta **dos operadores en una sola consulta** — así se arma un intervalo:

```
GET /api/register/customer?q[createdAt][AE]=2026-08-01 00:00:00&q[createdAt][BE]=2026-08-31 23:59:59
```

Genera `createdAt >= '2026-08-01 00:00:00' AND createdAt <= '2026-08-31 23:59:59'`.

> **Cuidado con la fecha sin hora en `BE`.** `q[createdAt][BE]=2026-08-31` significa `2026-08-31 00:00:00` — todo lo que pasó **durante** el día 31 queda fuera. O llegas hasta `23:59:59`, o usas `B` (menor que) en el día siguiente:
>
> ```
> q[createdAt][AE]=2026-08-01&q[createdAt][B]=2026-09-01
> ```

Un solo lado también sirve, cuando el intervalo es abierto:

```
q[order_date][AE]=2026-08-01     → del 1 de agosto en adelante
q[order_date][B]=2026-08-01      → antes del 1 de agosto
```

Recuerda aplicar URL-encode a los valores: el espacio se vuelve `%20` (o `+`), y `2026-08-01 00:00:00` queda como `2026-08-01%2000%3A00%3A00`.

### Cliente por correo exacto

```
GET /api/register/customer?q[email][E]=maria@ejemplo.com
```

Buscar un cliente **es esto** — el listado filtrado. No uses `create` ni `get-or-create` para consultar: escriben, y crean justo al cliente que solo querías encontrar.

### Un fragmento del texto

```
GET /api/register/customer?q[name][LRL]=silva
```

`LRL` es "contiene" (`LIKE '%silva%'`). Como casa cualquier fragmento, `q[email][LRL]=x@gmail.com` también trae `maria.mx@gmail.com` — para duplicados reales, usa `E`.

### Buscar en varias columnas a la vez

```
GET /api/register/customer?q[name;email][S]=maria silva
```

El término se parte por espacios: **cada palabra** debe aparecer en **al menos una** de las columnas. Las palabras se combinan con `Y`, las columnas con `O`.

### Varios valores en la misma columna

```
GET /api/order/data?q[status][IN]=completed&q[status][]=shipped
```

### Con valor o vacío

```
q[canceledAt][IS]=null      → solo los no cancelados
q[canceledAt][!IS]=null     → solo los cancelados
```

### Todo junto

```
GET /api/order/data?q[status][E]=completed&q[order_date][AE]=2026-08-01&q[order_date][B]=2026-09-01&o[order_date]=desc&e=50&p=2
```

Segunda página de 50 pedidos completados en agosto/2026, de los más nuevos a los más viejos.

## Antes de empezar a filtrar

- **Una columna no filtrable se ignora en silencio.** Algunos recursos limitan qué columnas aceptan filtro; cualquier otra se descarta sin error — y la respuesta vuelve **sin ese filtro**, con más filas de las que esperabas. Verifica el resultado en vez de asumirlo.
- **Sin operador es igualdad**: `q[status]=completed` hace lo mismo que `q[status][E]=completed`.
- **El nombre de la columna cambia por servicio.** Es `createdAt` en register y `order_date` / `createAt` en order — usa el mismo nombre que devuelve el endpoint.
- **`e=0` (o `e=all`) quita el límite.** En una base grande eso es una respuesta enorme y una consulta cara; mejor pagina.
