Filtros y búsqueda

Adicional a paginación y ordenamiento, los listados aceptan filtros ad-hoc por campo y un parámetro search para búsqueda libre.

search

Busca el texto en los campos de texto del modelo (CHAR, VARCHAR, TEXT) y en relaciones que tengan to_str. No distingue mayúsculas de minúsculas.

curl "http://localhost/api/v1/Cliente?search=acme" \
  -H "Authorization: Bearer $TOKEN"

Filtros por campo

Cualquier campo del modelo puede usarse como filtro pasándolo como query param. La igualdad es la operación por defecto.

curl "http://localhost/api/v1/Compra?proveedor=4218" \
  -H "Authorization: Bearer $TOKEN"

Operadores

Para rangos y comparaciones, agrega un sufijo al nombre del campo:

Sufijo	Operador	Ejemplo
(nada)	igualdad	`?id=42`
`__gt`	mayor que	`?total__gt=1000`
`__gte`	mayor o igual	`?fecha__gte=2026-01-01`
`__lt`	menor que	`?total__lt=1000`
`__lte`	menor o igual	`?fecha__lte=2026-12-31`
`__in`	dentro de un set	`?estado__in=A,B,C`
`__like`	LIKE (con `%`)	`?nombre__like=Acme%`
`__null`	IS NULL / NOT NULL	`?canceled_at__null=true`

curl "http://localhost/api/v1/Venta?fecha__gte=2026-01-01&fecha__lte=2026-03-31&total__gte=10000" \
  -H "Authorization: Bearer $TOKEN"

lean — sin relaciones resueltas

Por defecto, cada FK se resuelve a <fk>_str (la representación humana). En catálogos grandes esto duplica el costo del JOIN. Con ?lean=true solo recibes los IDs.

curl "http://localhost/api/v1/Compra?lean=true&per_page=100" \
  -H "Authorization: Bearer $TOKEN"

`lean`	Respuesta
`false` (default)	`{ "proveedor": 4218, "proveedor_str": "Acme S.A." }`
`true`	`{ "proveedor": 4218 }`

Combinando todo

curl "http://localhost/api/v1/Compra?\
proveedor__in=4218,4219&\
fecha__gte=2026-01-01&\
estado=I&\
sort=fecha&order=desc&\
page=1&per_page=50&\
lean=true" \
  -H "Authorization: Bearer $TOKEN"

(El \ al final de cada línea es solo para legibilidad en bash; en una sola línea funciona igual.)