Audiencias

Construye segmentos de usuarios/comercios con un query-builder, sin escribir SQL, y genera, valida y previsualiza la consulta resultante.

Descripción general

Un Audience Criteria es un segmento de usuarios o comercios definido con un query-builder —tabla → columnas → filtros → joins → agregaciones → combinación de bloques y audiencias— sin escribir SQL a mano.

La definición se arma componiendo:

Pieza	Qué aporta
Bloques de consulta	Uno o más bloques; cada bloque parte de una tabla del catálogo y define sobre ella columnas, filtros, tiempo, cruces y agregaciones.
Filtros	Condiciones por columna con un operador de comparación (`EQUALS`, `IN`, `BETWEEN`, …).
Filtros de registro	Condiciones sobre los elementos de una columna RECORD REPEATED (`attributes`): existe al menos un elemento que cumple el sub-filtro.
Ventana temporal	Acota el bloque a un período de tiempo (`IN_THE_LAST 30 DAYS`, `SINCE`, …).
Cruces (joins)	Une el bloque con otras tablas del catálogo (`INNER`, `LEFT`, …).
Agregaciones	Resume columnas del bloque en una métrica (`COUNT`, `SUM`, `AVG`, …).
Composiciones	Combina varios bloques y otras audiencias con operadores de conjunto (`UNION_DISTINCT`, …).

Columna de identidad

Toda audience criteria es un segmento con identidad propia: al menos uno de sus bloques de consulta debe proyectar la columna de identidad de la tabla base (por ejemplo user_id). La regla es incondicional — una definición que no la expone se rechaza con 400.

Endpoints

Catálogo

GET /tables y GET /tables/:tableName/columns — qué tablas y columnas se pueden filtrar.

Listar

GET /audience-criterias — lista paginada con búsqueda por nombre.

Obtener

GET /audience-criterias/:id — detalle completo de un criterio.

Crear

POST /audience-criterias — crea un criterio a partir de su definición.

Actualizar

PATCH /audience-criterias/:id — actualiza un criterio existente.

Eliminar

DELETE /audience-criterias/:id — elimina un criterio.

Generar SQL

POST /generate-sql y GET /:id/sql — obtiene el SQL de una definición.

Validar

POST /validate-from-body y POST /:id/validate — valida una definición.

Previsualizar

POST /preview-from-body y POST /:id/preview — ejecuta una muestra acotada.

Base URL y ambientes

Todas las rutas cuelgan del prefijo global /api bajo el recurso /audience-criterias (por ejemplo POST /api/audience-criterias).

Ambientes de Reten

Ambiente	Panel de Admin	API Base URL
Development	app-development.reten.ai	`https://api-development.reten.ai`
Staging	app-staging.reten.ai	`https://api-staging.reten.ai`
Production	app.reten.ai	`https://api.reten.ai`

Usa la URL del panel de admin para gestionar claves de API y configuraciones de dispatch. Reemplaza BASE_URL en los ejemplos de código con la API Base URL de tu ambiente.

Autenticación

Todos los endpoints requieren un token JWT Bearer más la cabecera x-tenant-id que identifica el tenant sobre cuyo esquema opera la solicitud, y la cabecera x-project-id que identifica el proyecto en el que trabaja la solicitud (ver Autenticación → Contexto de Proyecto).

Cabecera	Obligatoria	Valor
`Authorization`	Sí	`Bearer <access_token>`
`x-tenant-id`	Sí	UUID del tenant
`x-project-id`	Sí	UUID del proyecto

-H "Authorization: Bearer <access_token>"
-H "x-tenant-id: <tenant-id>"
-H "x-project-id: <project-id>"

Permisos

Cada ruta exige un permiso específico:

Permiso	Endpoints
`audience-criteria:view`	`GET /audience-criterias`, `GET /audience-criterias/:id`, `GET /tables`, `GET /tables/:tableName/columns`
`audience-criteria:create`	`POST /audience-criterias`
`audience-criteria:update`	`PATCH /audience-criterias/:id`
`audience-criteria:delete`	`DELETE /audience-criterias/:id`
`audience-criteria:view-sql`	`POST /generate-sql`, `GET /:id/sql`, `POST /validate-from-body`, `POST /:id/validate`, `POST /preview-from-body`, `POST /:id/preview`

Códigos de estado

Los endpoints POST de solo lectura (generate-sql, validate-*, preview-*) responden 201 Created —no 200—, aunque no creen ningún recurso.

Método + ruta	Código	Cuerpo de respuesta
`POST /audience-criterias` (crear)	`201`	El criterio creado
`GET /audience-criterias`	`200`	Lista paginada
`GET /audience-criterias/:id`	`200`	El criterio
`GET /tables`	`200`	Tablas del catálogo
`GET /tables/:tableName/columns`	`200`	Columnas del catálogo
`PATCH /audience-criterias/:id`	`200`	El criterio actualizado
`DELETE /audience-criterias/:id`	`204`	(sin cuerpo)
`POST /generate-sql`	`201`	SQL generado
`GET /:id/sql`	`200`	SQL generado
`POST /validate-from-body`	`201`	Resultado de validación
`POST /:id/validate`	`201`	Resultado de validación
`POST /preview-from-body`	`201`	Resultado de la muestra
`POST /:id/preview`	`201`	Resultado de la muestra

Formato de error

Los errores siguen el formato estándar de la API:

{
  "statusCode": 400,
  "message": ["name should not be empty"],
  "error": "Bad Request"
}

En errores de validación de DTO, message es un arreglo de strings (una entrada por regla incumplida). La validación es estricta: se rechazan propiedades no declaradas, así que enviar un campo desconocido produce un 400.

Errores comunes en esta API:

400 Bad Request — definición o DTO inválido (campo faltante, tipo incorrecto, enum fuera de rango, propiedad desconocida).
401 Unauthorized — falta o es inválido el Authorization: Bearer.
403 Forbidden — el usuario no tiene el permiso requerido, o el x-tenant-id no está autorizado.
404 Not Found — el id solicitado no existe en el proyecto activo.

Paginación

El listado envuelve los resultados en PaginatedResponseDto<T>:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "total_pages": 0,
    "has_next": false,
    "has_previous": false
  }
}

Los campos dentro de pagination usan snake_case (per_page, total_pages, has_next, has_previous), a diferencia del resto del recurso que usa camelCase.

El detalle de los parámetros de paginación (page, per_page, filtros) se documenta en Listar.

Glosario de enums

Catálogo de referencia rápida. Cada página de endpoint vuelve a listar los valores válidos junto al campo donde aparecen.

`SetOperatorEnum`

Combinación de bloques/audiencias en composedWith.

UNION_DISTINCT · UNION_ALL · INTERSECT_DISTINCT

`LogicalOperatorEnum`

Encadenamiento de predicados dentro de un grupo.

AND · OR

`ComparisonOperatorEnum`

Operador de un predicado sobre una columna.

EQUALS · NOT_EQUALS · GREATER_THAN · LESS_THAN · GREATER_THAN_OR_EQUAL · LESS_THAN_OR_EQUAL · CONTAINS · NOT_CONTAINS · STARTS_WITH · ENDS_WITH · IS_NULL · IS_NOT_NULL · IN · NOT_IN · BETWEEN

`AggregationOperatorEnum`

Función de agregación sobre un operando (una columna, * o una expresión aritmética).

COUNT · SUM · AVG · MIN · MAX

`ArithmeticOperatorEnum`

Operador de una expresión aritmética dentro del operando de un agregado. SAFE_DIVIDE da NULL cuando el denominador es cero.

ADD · SUBTRACT · MULTIPLY · SAFE_DIVIDE

`TimeOperatorEnum`

Operador de la ventana temporal (timeWindow).

ALL_TIME · IN_THE_LAST · IN_THE_FIRST · SINCE · BETWEEN

`TimeUnitEnum`

Unidad de la ventana temporal.

DAYS · WEEKS · MONTHS · YEARS

`JoinTypeEnum`

Tipo de join entre tablas del catálogo.

INNER · LEFT · RIGHT · FULL

`CatalogFieldTypeEnum`

Tipo de dato de un campo del catálogo de audiencias.

STRING · TIMESTAMP · BOOLEAN · FLOAT64 · INT64 · NUMERIC · BIGNUMERIC

Forma del valor según el operador de comparación

La forma que toma value depende del comparisonOperator del predicado:

Operadores	Forma de `value`	Ejemplo
`IS_NULL`, `IS_NOT_NULL`	Sin valor (`NONE`)	(se omite)
`IN`, `NOT_IN`	Lista no vacía (`LIST`)	`["a", "b", "c"]`
`BETWEEN`	Par ordenado (`RANGE`)	`[10, 20]`
El resto (`EQUALS`, `GREATER_THAN`, `CONTAINS`, …)	Escalar único (`SINGLE`)	`"activo"` · `42`