CAPÍTULO 02
Paginación, filtros con operadores y ordenamiento múltiple
02 — Listar, filtrar y ordenar
Cualquier recurso de la API se puede listar con un GET a su ruta. La API soporta paginación, filtrado por columna con operadores, ordenamiento múltiple y combinación AND/OR.
Listado básico
GET https://<tu-instancia>.beply.es/api/3/clientesDevuelve un array JSON con los primeros 50 registros del recurso.
Paginación
| Parámetro | Default | Descripción |
|---|---|---|
limit | 50 | Número máximo de registros por respuesta |
offset | 0 | Cuántos registros saltar desde el inicio |
Ejemplo: página 2 de 25 en 25
GET /api/3/clientes?limit=25&offset=25Total de registros
La API devuelve el total sin paginar en la cabecera de respuesta:
X-Total-Count: 1247Útil para construir paginadores en tu UI:
const res = await fetch(url, { headers: { 'Token': key } })
const total = Number(res.headers.get('X-Total-Count'))
const pages = Math.ceil(total / 25)
const data = await res.json()Filtros
Sintaxis general: filter[<columna>]=<valor>.
Operadores
| Sufijo | Comparación | Ejemplo |
|---|---|---|
| (ninguno) | = (igualdad) | filter[codcliente]=1 |
_neq | ≠ | filter[pagada_neq]=1 |
_gt | > | filter[total_gt]=1000 |
_gte | ≥ | filter[fecha_gte]=2026-01-01 |
_lt | < | filter[stock_lt]=10 |
_lte | ≤ | filter[total_lte]=500 |
_like | contiene | filter[nombre_like]=Distribuciones |
Combinar varios filtros (AND)
Por defecto, varios filtros se aplican con AND:
GET /api/3/facturaclientes?filter[pagada]=0&filter[fecha_gte]=2026-05-01Facturas no pagadas Y emitidas a partir del 1 de mayo de 2026.
Cambiar a OR
Para que un filtro concreto se combine con OR en vez de AND, añade operation[<columna>_<op>]=OR:
GET /api/3/productos?filter[descripcion_like]=PESO&filter[familia]=ACC&operation[familia]=ORProductos que tengan “PESO” en la descripción O pertenezcan a la familia “ACC”.
Ordenamiento
Sintaxis: sort[<columna>]=<ASC|DESC>.
Puedes ordenar por varias columnas (se aplica el orden de aparición):
GET /api/3/clientes?sort[provincia]=ASC&sort[nombre]=ASCGET /api/3/facturaclientes?sort[fecha]=DESC&sort[total]=DESCEjemplos completos
Top 10 clientes con más facturación este año, ordenados por importe
GET /api/3/clientes?limit=10&sort[totalfacturado]=DESCFacturas pendientes vencidas, ordenadas por antigüedad
GET /api/3/facturaclientes \
?filter[pagada]=0 \
&filter[vencimiento_lt]=2026-05-20 \
&sort[vencimiento]=ASCBuscar productos por descripción y código a la vez
GET /api/3/productos \
?filter[descripcion_like]=tornillo \
&filter[referencia_like]=TN \
&operation[referencia_like]=ORPróximos pasos
- 03 — CRUD básico: obtener uno, crear, modificar, eliminar
- 04 — Facturas: listado + endpoints específicos de facturación