Filtros dinámicos

Refina los resultados de cualquier consulta GET agregando filtros directamente en la URL de la solicitud.

⚠️
Disponibilidad: Los filtros dinámicos no están habilitados en todos los endpoints. Solo puedes utilizarlos en aquellos que lo indiquen explícitamente en su documentación de referencia. Consulta la página de cada endpoint para verificar si soporta filtros y qué campos están disponibles.

🔷 ¿Cómo funcionan los filtros?

Todos los filtros aplicados en una misma consulta se evalúan bajo una lógica de cumplimiento obligatorio (AND). Esto significa que los resultados mostrados serán solo aquellos que cumplan con todas las condiciones enviadas simultáneamente.

🔷 Estructura del filtro

Cada filtro se compone de tres partes: el nombre del campo, el operador de comparación y el valor deseado.

Formato estándar:

campo[operador]=valor

Ejemplo: Buscar órdenes de trabajo cuyo estado sea "open" y cuyo costo sea mayor o igual a 100:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&cost[gte]=100

🔷 Operadores disponibles

A continuación, se detallan los operadores permitidos según el tipo de información que contenga el campo (texto, números o fechas).

Operador	Descripción	Tipos de dato soportados
eq	Igualdad exacta	texto, número, fecha, booleano
neq	Diferente de	texto, número, fecha, booleano
gt	Mayor que	número, fecha
gte	Mayor o igual que	número, fecha
lt	Menor que	número, fecha
lte	Menor o igual que	número, fecha
like	Búsqueda parcial (que contenga el texto)	texto
between	Rango entre dos valores	número, fecha
in	Lista de valores (separados por coma)	solo números

🔷 Funcionamiento de operadores

Igualdad y Diferencia

Busca una coincidencia exacta (eq) o excluye registros específicos (neq).

Ejemplos:

?id[eq]=3 (Solo el registro con ID 3)
?id[neq]=1 (Todos los registros excepto el ID 1)
?status[eq]=open (Órdenes de trabajo con estado "open")

🔷 Aplicación de múltiples filtros

Combina varias condiciones en una sola solicitud utilizando el símbolo &. El sistema devuelve solo los registros que cumplan todas las condiciones a la vez.

Ejemplo: Buscar órdenes de trabajo que no sean la #3, con costo menor a 500 y descripción que contenga "urgente":

GET https://app.fracttal.com/api/work_orders?id[neq]=3&cost[lt]=500&description[like]=urgente

🔷 Filtrado por fechas

Las fechas son uno de los filtros más usados. La API espera fechas en formato ISO 8601: YYYY-MM-DDTHH:MM:SS±UTC.

Filtra órdenes de trabajo creadas en enero de 2024:

GET https://app.fracttal.com/api/work_orders?date[between]=2024-01-01T00:00:00-05,2024-01-31T23:59:59-05

Alternativa a between usando dos filtros separados. Filtra órdenes de trabajo entre el 1 de marzo y el 30 de junio de 2024:

GET https://app.fracttal.com/api/work_orders?date[gte]=2024-03-01T00:00:00-05&date[lte]=2024-06-30T23:59:59-05

Esta forma es útil cuando necesitas combinar el rango de fechas con otros filtros adicionales.

El signo + en una zona horaria debe codificarse como %2B en la URL. Si no se codifica, el servidor lo interpreta como un espacio y la consulta falla.

❌ Incorrecto:

?date[gt]=2024-01-01T00:00:00+02

✅ Correcto:

?date[gt]=2024-01-01T00:00:00%2B02

🔷 Ejemplo completo de solicitud y respuesta

A continuación se muestra una solicitud real con filtros aplicados y las posibles respuestas.

Solicitud: Obtener órdenes de trabajo con estado "open" y costo mayor o igual a 100:

curl -X GET "https://app.fracttal.com/api/work_orders?status[eq]=open&cost[gte]=100" \
  -H "Authorization: Bearer TU_TOKEN"

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "wo_folio": "OT-001234",
      "description": "Mantenimiento preventivo bomba hidráulica",
      "status": "open",
      "cost": 250.00,
      "date": "2024-03-15T10:30:00-05"
    },
    {
      "wo_folio": "OT-001289",
      "description": "Revisión sistema eléctrico planta norte",
      "status": "open",
      "cost": 180.50,
      "date": "2024-03-20T08:00:00-05"
    }
  ],
  "total": 2
}

Ejemplo: se usa el operador like en un campo numérico (cost):

curl -X GET "https://app.fracttal.com/api/work_orders?cost[like]=100" \
  -H "Authorization: Bearer TU_TOKEN"

{
  "success": false,
  "message": "Error de validación",
  "errors": [
    {
      "field": "cost",
      "operator": "like",
      "error": "El operador 'like' no es compatible con campos numéricos."
    }
  ]
}

🔷 Errores comunes y solución

Error	Causa	Solución
Operador incompatible con el tipo de dato	Usar `like` en un campo numérico o `in` en un campo de texto	Consulta la tabla de operadores y verifica los tipos de dato soportados por cada uno
Exceso de filtros	Enviar más de 20 filtros en una sola solicitud	Reduce el número de condiciones o divide la consulta en varias solicitudes
Exceso de valores en `in`	Enviar más de 100 valores en una lista `in`	Divide los valores en múltiples solicitudes con listas de 100 o menos
Formato incorrecto de fecha	No seguir el formato ISO 8601 (`YYYY-MM-DDTHH:MM:SS±UTC`)	Usa el formato correcto: `2024-01-01T00:00:00-05`
Zona horaria con `+` sin codificar	Escribir `+02` en vez de `%2B02` en la URL	Codifica el signo `+` como `%2B`
Operador `between` con valores incorrectos	Enviar más o menos de 2 valores separados por coma	Asegúrate de enviar exactamente dos valores: `?campo[between]=min,max`

🔷 Campos filtrables por endpoint

📌
No todos los endpoints soportan los mismos campos de filtrado. Los campos disponibles dependen del recurso que estés consultando. Consulta la documentación de referencia de cada endpoint para conocer los campos específicos que acepta como filtro.
Por ejemplo:

Órdenes de trabajo (/work_orders): status, cost, date, description, entre otros.

Activos (/items): code, description, status, entre otros.

Medidores (/meters): code, serial, entre otros.

🔷 Ordenamiento y paginación

Los filtros se pueden combinar con parámetros de ordenamiento y paginación para controlar los resultados de forma precisa.

Parámetros disponibles:

Parámetro	Descripción	Ejemplo
`sort`	Campo por el cual ordenar los resultados	`sort=date`
`order`	Dirección del ordenamiento: `asc` (ascendente) o `desc` (descendente)	`order=desc`
`page`	Número de página de resultados	`page=1`
`limit`	Cantidad máxima de registros por página	`limit=50`

Ejemplo completo: Obtener órdenes de trabajo con estado "open", ordenadas por fecha descendente, mostrando 20 resultados por página:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&sort=date&order=desc&page=1&limit=20

🔷 Ejemplos en contexto Fracttal

Filtrar por estado y rango de fechas:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&date[gte]=2024-01-01T00:00:00-05&date[lte]=2024-03-31T23:59:59-05

Buscar por descripción y costo mínimo:

GET https://app.fracttal.com/api/work_orders?description[like]=preventivo&cost[gte]=500

Buscar activos cuya descripción contenga "bomba":

GET https://app.fracttal.com/api/items?description[like]=bomba

Filtrar activos activos excluyendo un código específico:

GET https://app.fracttal.com/api/items?status[eq]=ACTIVE&code[neq]=ACT-0001

Consultar lecturas de un medidor por rango de fechas:

GET https://app.fracttal.com/api/meters_reading?date[between]=2024-01-01,2024-06-30

Filtrar medidores por código de activo:

GET https://app.fracttal.com/api/meters?code[eq]=MED-0042

Filtrar solicitudes por estado y fecha de creación:

GET https://app.fracttal.com/api/work_requests?status[eq]=PENDING&date[gte]=2024-06-01T00:00:00-05

Buscar solicitudes cuya descripción contenga "eléctrico":

GET https://app.fracttal.com/api/work_requests?description[like]=eléctrico

🔷 Consideraciones importantes

💡
Reglas de validación

Límite de condiciones: Se permite un máximo de 20 filtros por solicitud.

Límite de lista (IN): El operador in permite un máximo de 100 valores por lista.

Compatibilidad: Asegúrate de usar el operador correcto para el tipo de dato. Por ejemplo, intentar usar like en un campo de precio o in en un campo de descripción generará un error de validación.

Caracteres especiales en fechas: Al filtrar por fechas que incluyan zonas horarias con el signo más (+), este debe escribirse como %2B.

Correcto: ?date[gt]=2024-01-01T00:00:00%2B02

Filtros dinámicos

🔷 ¿Cómo funcionan los filtros?

🔷 Estructura del filtro

🔷 Operadores disponibles

🔷 Funcionamiento de operadores

Igualdad y Diferencia

Búsqueda parcial

Comparaciones de magnitud

Rangos de valores

Selección múltiple

🔷 Aplicación de múltiples filtros

🔷 Filtrado por fechas

🔷 Ejemplo completo de solicitud y respuesta

🔷 Errores comunes y solución

🔷 Campos filtrables por endpoint

🔷 Ordenamiento y paginación

🔷 Ejemplos en contexto Fracttal

🔷 Consideraciones importantes