Entrar
.md

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 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.