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áticaq[], 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, esq[], 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/1para ascendente,DESC/desc/0para 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-31significa2026-08-31 00:00:00— todo lo que pasó durante el día 31 queda fuera. O llegas hasta23:59:59, o usasB(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]=completedhace lo mismo queq[status][E]=completed. - El nombre de la columna cambia por servicio. Es
createdAten register yorder_date/createAten order — usa el mismo nombre que devuelve el endpoint. e=0(oe=all) quita el límite. En una base grande eso es una respuesta enorme y una consulta cara; mejor pagina.