Sistema de filtrado (Criteria)

La mayoría de endpoints de listado soportan un sistema avanzado de filtrado a través de query parameters. Este sistema permite construir consultas complejas combinando múltiples filtros.

Estructura de un filtro

Cada filtro es un objeto con tres propiedades:

Propiedad	Tipo	Descripción
`field`	`string`	Nombre del campo a filtrar
`operator`	`string`	Operador de comparación
`value`	`string \| string[]`	Valor o valores a comparar

Operadores disponibles

Operador	Descripción	Tipo de `value`
`=`	Igual a	`string`
`!=`	Distinto de	`string`
`>`	Mayor que	`string`
`>=`	Mayor o igual que	`string`
`<`	Menor que	`string`
`<=`	Menor o igual que	`string`
`CONTAINS`	Contiene (búsqueda parcial)	`string`
`NOT_CONTAINS`	No contiene	`string`
`IN`	Está en la lista	`string[]`
`NOT_IN`	No está en la lista	`string[]`

Parámetros de paginación y orden

Parámetro	Tipo	Default	Descripción
`filters`	`array`	`[]`	Array de filtros
`orderBy`	`string`	`null`	Campo por el cual ordenar
`order`	`string`	`null`	Dirección: `asc`, `desc` o `none`
`limit`	`integer`	`25`	Resultados por página (máx. 100)
`offset`	`integer`	`0`	Desplazamiento de resultados

Ejemplo de petición con filtros

GET /v1/bookings?filters[0][field]=status&filters[0][operator]==&filters[0][value]=confirmed&filters[1][field]=startTime&filters[1][operator]=>=&filters[1][value]=2026-03-05T00:00:00Z&orderBy=startTime&order=asc&limit=10&offset=0

Filtrado por Custom Fields

Los endpoints de Bookings y Clients permiten filtrar por campos personalizados usando el UUID del campo como valor de field. Esto permite construir filtros dinámicos basados en los campos personalizados definidos por el negocio.

GET /v1/clients?filters[0][field]=a1b2c3d4-e5f6-7890-abcd-ef1234567890&filters[0][operator]==&filters[0][value]=premium

Para obtener la lista de campos personalizados disponibles y sus UUIDs, consulta el endpoint GET /custom-fields.

Campos filtrables por recurso

Bookings

Campo	Descripción
`id`	UUID de la reserva
`startTime`	Fecha/hora de inicio
`endTime`	Fecha/hora de fin
`status`	Estado de la reserva
`internalNote`	Nota interna
`clientNote`	Nota del cliente
`paymentStatus`	Estado de pago
`isFromWeb`	Si fue creada desde la web
`isFromAgent`	Si fue creada por el agente IA
`amount`	Monto
`clientId`	UUID del cliente
`paymentId`	UUID del pago
`locationId`	UUID de la ubicación
`serviceId`	UUID del servicio
`personId`	UUID del profesional
`createdAt`	Fecha de creación
`client`	Nombre del cliente (búsqueda)
`clientCustomField`	Campo personalizado del cliente
`clientPhone`	Teléfono del cliente
`clientDocNumber`	Número de documento del cliente
`clientBirthdate`	Fecha de nacimiento del cliente
`clientCountry`	País del cliente
`clientState`	Estado/Provincia del cliente
`clientCity`	Ciudad del cliente
`{uuid}`	UUID de un campo personalizado

Clients

Campo	Descripción
`id`	UUID del cliente
`fullname`	Nombre completo
`email`	Email
`phone`	Teléfono
`docType`	Tipo de documento
`docNumber`	Número de documento
`birthdate`	Fecha de nacimiento
`address`	Dirección
`city`	Ciudad
`state`	Estado/Provincia
`country`	País
`{uuid}`	UUID de un campo personalizado

Locations

Campo	Descripción
`name`	Nombre de la ubicación
`code`	Código
`status`	Estado

Services

Campo	Descripción
`id`	UUID del servicio
`name`	Nombre
`duration`	Duración en minutos
`domiciliary`	Si es a domicilio
`virtual`	Si es virtual
`status`	Estado
`price`	Precio
`categoryId`	UUID de la categoría
`description`	Descripción
`sessions`	Número de sesiones
`simultaneous`	Citas simultáneas

People (Profesionales)

Campo	Descripción
`locationId`	UUID de la ubicación
`fullname`	Nombre completo
`email`	Email
`status`	Estado
`phone`	Teléfono
`idType`	Tipo de identificación
`idNumber`	Número de identificación
`birthdate`	Fecha de nacimiento
`userId`	UUID del usuario asociado
`service.id`	UUID del servicio asociado

Calendar Events

Campo	Descripción
`id`	UUID del evento
`type`	Tipo de evento (`booking`, `time_block`)
`startTime`	Fecha/hora de inicio
`endTime`	Fecha/hora de fin
`locationId`	UUID de la ubicación
`providerId`	UUID del profesional