Audiências

Construa segmentos de usuários/comércios com um query-builder, sem escrever SQL, e gere, valide e visualize a consulta resultante.

Visão geral

Um Audience Criteria é um segmento de usuários ou comércios definido com um query-builder —tabela → colunas → filtros → joins → agregações → combinação de blocos e audiências— sem escrever SQL manualmente.

A definição é montada compondo:

Peça	O que fornece
Blocos de consulta	Um ou mais blocos; cada bloco parte de uma tabela do catálogo e define sobre ela colunas, filtros, tempo, joins e agregações.
Filtros	Condições por coluna com um operador de comparação (`EQUALS`, `IN`, `BETWEEN`, …).
Filtros de registro	Condições sobre os elementos de uma coluna RECORD REPEATED (`attributes`): pelo menos um elemento satisfaz o sub-filtro.
Janela temporal	Restringe o bloco a um período de tempo (`IN_THE_LAST 30 DAYS`, `SINCE`, …).
Joins	Une o bloco com outras tabelas do catálogo (`INNER`, `LEFT`, …).
Agregações	Resume colunas do bloco em uma métrica (`COUNT`, `SUM`, `AVG`, …).
Composições	Combina vários blocos e outras audiências com operadores de conjunto (`UNION_DISTINCT`, …).

Coluna de identidade

Toda audience criteria é um segmento com identidade própria: pelo menos um de seus blocos de consulta deve projetar a coluna de identidade da tabela base (por exemplo user_id). A regra é incondicional — uma definição que não a expõe é rejeitada com 400.

Endpoints

Catálogo

GET /tables e GET /tables/:tableName/columns — quais tabelas e colunas podem ser filtradas.

Listar

GET /audience-criterias — lista paginada com busca por nome.

Obter

GET /audience-criterias/:id — detalhe completo de um critério.

Criar

POST /audience-criterias — cria um critério a partir de sua definição.

Atualizar

PATCH /audience-criterias/:id — atualiza um critério existente.

Excluir

DELETE /audience-criterias/:id — exclui um critério.

Gerar SQL

POST /generate-sql e GET /:id/sql — obtém o SQL de uma definição.

Validar

POST /validate-from-body e POST /:id/validate — valida uma definição.

Pré-visualizar

POST /preview-from-body e POST /:id/preview — executa uma amostra limitada.

Base URL e ambientes

Todas as rotas ficam sob o prefixo global /api, dentro do recurso /audience-criterias (por exemplo POST /api/audience-criterias).

Ambientes da Reten

Ambiente	Painel 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`

Use a URL do painel de admin para gerenciar chaves de API e configurações de dispatch. Substitua BASE_URL nos exemplos de código pela API Base URL do seu ambiente.

Autenticação

Todos os endpoints exigem um token JWT Bearer mais o header x-tenant-id que identifica o tenant em cujo schema a requisição opera, e o header x-project-id que identifica o projeto em que a requisição trabalha (veja Autenticação → Contexto de Projeto).

Header	Obrigatório	Valor
`Authorization`	Sim	`Bearer <access_token>`
`x-tenant-id`	Sim	UUID do tenant
`x-project-id`	Sim	UUID do projeto

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

Permissões

Cada rota exige uma permissão específica:

Permissão	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 status

Os endpoints POST somente leitura (generate-sql, validate-*, preview-*) respondem 201 Created —e não 200—, mesmo que não criem nenhum recurso.

Método + rota	Código	Corpo da resposta
`POST /audience-criterias` (criar)	`201`	O critério criado
`GET /audience-criterias`	`200`	Lista paginada
`GET /audience-criterias/:id`	`200`	O critério
`GET /tables`	`200`	Tabelas do catálogo
`GET /tables/:tableName/columns`	`200`	Colunas do catálogo
`PATCH /audience-criterias/:id`	`200`	O critério atualizado
`DELETE /audience-criterias/:id`	`204`	(sem corpo)
`POST /generate-sql`	`201`	SQL gerado
`GET /:id/sql`	`200`	SQL gerado
`POST /validate-from-body`	`201`	Resultado da validação
`POST /:id/validate`	`201`	Resultado da validação
`POST /preview-from-body`	`201`	Resultado da amostra
`POST /:id/preview`	`201`	Resultado da amostra

Formato de erro

Os erros seguem o formato padrão da API:

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

Em erros de validação de DTO, message é um array de strings (uma entrada por regra violada). A validação é estrita: propriedades não declaradas são rejeitadas, então enviar um campo desconhecido produz um 400.

Erros comuns nesta API:

400 Bad Request — definição ou DTO inválido (campo ausente, tipo incorreto, enum fora do intervalo, propriedade desconhecida).
401 Unauthorized — o Authorization: Bearer está ausente ou é inválido.
403 Forbidden — o usuário não tem a permissão necessária, ou o x-tenant-id não está autorizado.
404 Not Found — o id solicitado não existe no projeto ativo.

Paginação

A listagem envolve os resultados em PaginatedResponseDto<T>:

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

Os campos dentro de pagination usam snake_case (per_page, total_pages, has_next, has_previous), diferente do resto do recurso que usa camelCase.

O detalhe dos parâmetros de paginação (page, per_page, filtros) está documentado em Listar.

Glossário de enums

Catálogo de referência rápida. Cada página de endpoint relista os valores válidos junto ao campo onde aparecem.

`SetOperatorEnum`

Combinação de blocos/audiências em composedWith.

UNION_DISTINCT · UNION_ALL · INTERSECT_DISTINCT

`LogicalOperatorEnum`

Encadeamento de predicados dentro de um grupo.

AND · OR

`ComparisonOperatorEnum`

Operador de um predicado sobre uma coluna.

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`

Função de agregação sobre um operando (uma coluna, * ou uma expressão aritmética).

COUNT · SUM · AVG · MIN · MAX

`ArithmeticOperatorEnum`

Operador de uma expressão aritmética dentro do operando de um agregado. SAFE_DIVIDE retorna NULL quando o denominador é zero.

ADD · SUBTRACT · MULTIPLY · SAFE_DIVIDE

`TimeOperatorEnum`

Operador da janela temporal (timeWindow).

ALL_TIME · IN_THE_LAST · IN_THE_FIRST · SINCE · BETWEEN

`TimeUnitEnum`

Unidade da janela temporal.

DAYS · WEEKS · MONTHS · YEARS

`JoinTypeEnum`

Tipo de join entre tabelas do catálogo.

INNER · LEFT · RIGHT · FULL

`CatalogFieldTypeEnum`

Tipo de dado de um campo do catálogo de audiências.

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

Forma do valor segundo o operador de comparação

A forma que value assume depende do comparisonOperator do predicado:

Operadores	Forma de `value`	Exemplo
`IS_NULL`, `IS_NOT_NULL`	Sem valor (`NONE`)	(omitido)
`IN`, `NOT_IN`	Lista não vazia (`LIST`)	`["a", "b", "c"]`
`BETWEEN`	Par ordenado (`RANGE`)	`[10, 20]`
O resto (`EQUALS`, `GREATER_THAN`, `CONTAINS`, …)	Escalar único (`SINGLE`)	`"ativo"` · `42`