Criar filtro de eventos

Crie um filtro de eventos a partir de sua definição completa (blocos de consulta, filtros, janela temporal e agregações).

POST /api/event-criterias

Cria um filtro de eventos a partir de sua definição completa. A operação é transacional: o filtro e seus blocos de consulta são criados juntos, ou nada é criado.

Auth: Obrigatória — permissão event-criteria:create

Corpo da requisição

Nível raiz (CreateEventCriteriaDto):

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do filtro. Não pode ser vazio.
`description`	string	Não	Descrição de texto livre. Se omitida, a resposta a retorna como `null`.
`queryBlocks`	`QueryBlockDto[]`	Sim	Mínimo 1 elemento. Cada bloco ≈ um statement SQL completo.

A estrutura de cada bloco —order, setOperator, from, select, timeWindow, where, groupBy, having— está em Definição.

Não existe composedWith: um filtro de eventos não se compõe com outros filtros. Enviá-lo produz um 400 por propriedade desconhecida.

Exemplos

Filtro de coluna

Eventos cujo status é Facturada.

curl -X POST https://api.reten.ai/api/event-criterias \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Venta oficial — solo facturada",
    "description": "Definición canónica de evento válido",
    "queryBlocks": [
      {
        "order": 0,
        "from": { "table": "event_transactions", "joins": [] },
        "select": {
          "distinct": true,
          "items": [
            { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
          ]
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "event_transactions", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "Facturada"
            }
          ]
        }
      }
    ]
  }'

import axios from 'axios';

const body = {
  name: 'Venta oficial — solo facturada',
  description: 'Definición canónica de evento válido',
  queryBlocks: [
    {
      order: 0,
      from: { table: 'event_transactions', joins: [] },
      select: {
        distinct: true,
        items: [
          { kind: 'column', column: { table: 'event_transactions', column: 'event_id' } },
        ],
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'event_transactions', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'Facturada',
          },
        ],
      },
    },
  ],
};

const response = await axios.post(
  'https://api.reten.ai/api/event-criterias',
  body,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const created = response.data;

Filtro de registro

Eventos que têm um atributo cuja key é documento_tipo e cujo value é factura — as duas condições sobre o mesmo elemento de attributes.

{
  "name": "Documentos tipo factura",
  "queryBlocks": [
    {
      "order": 0,
      "from": { "table": "event_transactions", "joins": [] },
      "select": {
        "distinct": true,
        "items": [
          { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
        ]
      },
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "recordPredicate",
            "column": { "table": "event_transactions", "column": "attributes" },
            "subWhere": {
              "kind": "group",
              "logicalOperator": "AND",
              "children": [
                { "kind": "predicate", "field": "key", "comparisonOperator": "EQUALS", "value": "documento_tipo" },
                { "kind": "predicate", "field": "value", "comparisonOperator": "EQUALS", "value": "factura" }
              ]
            }
          }
        ]
      }
    }
  ]
}

Filtro de tabela relacionada

Eventos faturados com ao menos uma linha cujo produto é da categoria Food Service ou HORECA. O caminho até product_properties é resolvido pelo catálogo: a requisição apenas nomeia o semi-join.

{
  "name": "Proyecto Food Service",
  "queryBlocks": [
    {
      "order": 0,
      "from": { "table": "event_transactions", "joins": [] },
      "select": {
        "distinct": true,
        "items": [
          { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
        ]
      },
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "event_transactions", "column": "status" },
            "comparisonOperator": "EQUALS",
            "value": "Facturada"
          },
          {
            "kind": "semiJoinPredicate",
            "table": "event_transactions",
            "semiJoin": "products",
            "subWhere": {
              "kind": "group",
              "logicalOperator": "AND",
              "children": [
                {
                  "kind": "predicate",
                  "field": "categorization.category_name",
                  "comparisonOperator": "IN",
                  "value": ["Food Service", "HORECA"]
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Retorna o filtro criado como IEventCriteriaDetail — a mesma forma que GET /event-criterias/:id: o recurso base mais queryBlocks[], com seu id já resolvido e ordenados por order ascendente.

Campo	Tipo	Descrição
`id`	string (UUID)	Id do filtro criado.
`projectId`	string (UUID)	Projeto ao qual o filtro pertence.
`name`	string
`description`	string \| null	`null` se não for enviada.
`isActive`	boolean	Sempre `true`: nenhum endpoint o modifica.
`ownerId`	string (UUID)	Usuário criador.
`updatedBy`	string (UUID)	Último editor (na criação, o criador).
`createdAt`	string (ISO 8601)
`updatedAt`	string (ISO 8601)
`queryBlocks`	array	Os blocos persistidos, com seu `id`.

{
  "id": "9f3a1c22-4b7e-4c31-9a8d-2f5e6b7c8d90",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "name": "Venta oficial — solo facturada",
  "description": "Definición canónica de evento válido",
  "isActive": true,
  "ownerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "updatedBy": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "createdAt": "2026-07-10T09:12:44.005Z",
  "updatedAt": "2026-07-10T09:12:44.005Z",
  "queryBlocks": [
    {
      "id": "e5f6a708-91b2-4c33-8d44-5e6f7a8b9c01",
      "order": 0,
      "setOperator": null,
      "from": { "table": "event_transactions", "joins": [] },
      "select": {
        "distinct": true,
        "items": [
          { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
        ]
      },
      "timeWindow": null,
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "event_transactions", "column": "status" },
            "comparisonOperator": "EQUALS",
            "value": "Facturada"
          }
        ]
      },
      "groupBy": null,
      "having": null
    }
  ]
}

Regras de validação

A definição é validada antes de ser persistida: um filtro que não compila para SQL não é criado. O catálogo completo de regras e suas mensagens exatas está em Definição → Regras de validação.

Respostas de erro

Status	Descrição
`400`	DTO inválido (campo ausente, tipo incorreto, enum fora do intervalo, propriedade desconhecida) ou uma regra de negócio violada.
`401`	`Authorization: Bearer` ausente ou inválido.
`403`	O usuário não tem a permissão `event-criteria:create`, ou o `x-tenant-id` não está autorizado.